Update documentation (#26148)

maririos · jnlycklama · commit 687719aa094b · 2023-11-08T12:27:49.000-08:00
diff --git a/.github/PULL_REQUEST_TEMPLATE/control_plane_template.md b/.github/PULL_REQUEST_TEMPLATE/control_plane_template.md
@@ -20,7 +20,7 @@ If you need further help with anything, see `Getting help` section below.
 
 What's the purpose of this PR? Check all that apply. This is **mandatory**!
 
-  - [ ] New API version. (Such PR should have been generated with [OpenAPI Hub](https://aka.ms/openapihub), per [this wiki doc](https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/208/OpenAPI-Hub-Adding-new-API-version).)
+  - [ ] New API version. (Such PR should have been generated with [OpenAPI Hub](https://aka.ms/openapihub)).
   - [ ] Update existing version for a new feature. (This is applicable only when you are revising a private preview API version.)
   - [ ] Update existing version to fix swagger quality issues in S360.
   - [ ] Other, please clarify:
diff --git a/.github/PULL_REQUEST_TEMPLATE/data_plane_template.md b/.github/PULL_REQUEST_TEMPLATE/data_plane_template.md
@@ -27,7 +27,7 @@ in the `Generated ApiView` comment added to this PR. You can use ApiView to show
 ### Suppressing failures
 
 If one or multiple validation error/warning suppression(s) is detected in your PR, please follow the 
-[Swagger-Suppression-Process](https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/85/Swagger-Suppression-Process) 
+[Swagger-Suppression-Process](https://aka.ms/pr-suppressions) 
 to get approval.
 
 ## ❔Got questions? Need additional info?? We are here to help!
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -48,11 +48,7 @@ Because the first rule is to avoid breaking changes and because we want APIs to
 
 ## Coding Style
 
-REST APIs for Azure should be defined using the [OpenAPI v2](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md) or [Cadl](https://aka.ms/cadl/rpaas-start)format.
-
-The REST API should also adhere to the conventions documented in the [Azure API Style Guide](https://github.com/Azure/azure-api-style-guide/blob/main/openapi-style-guide.md).
-
-You can use the [Spectral linter](https://meta.stoplight.io/docs/spectral/674b27b261c3c-overview) with our [Spectral ruleset](https://github.com/Azure/azure-api-style-guide#how-to-use-the-spectral-ruleset) to check conformance with OpenAPI v2 and the Style Guide.
+All new services should use [TypeSpec](https://aka.ms/typespec/azure) to create their REST API definition. If you are working on an existing service, you should consider converting your existing REST API definition to TypeSpec. Services that use TypeSpec to describe their REST API should include both the TypeSpec source and generated OpenAPI in the specs repo.
 
 ## Directory Structure
 
@@ -69,7 +65,7 @@ If you want to contribute to the repository, follow these steps:
   5. Resolve any issues flagged by the [Pull Request checks](#pull-request-checks).
   6. Contact the ARM API Review board or Azure API Stewardship team to request PR review. 
 
-Microsoft employees can try out the experience at [OpenAPI Hub](https://aka.ms/openapihub) for [adding a new API version using OpenAPI Hub](https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/208/OpenAPI-Hub-Adding-new-API-version).
+Microsoft employees can use [OpenAPI Hub](https://aka.ms/openapihub) for adding a new API version.
 
 ## Pull Request Checks
 
@@ -93,8 +89,4 @@ When any of these PR checks fails it will post a comment to the PR with links to
 There is also the [CI Fix Guide](https://aka.ms/ci-fix) that describes how to fix common PR check failures.
 
 ## Internal Contribution Guide
-For management plane, please refer to https://aka.ms/rpguidelines; 
-
-For data-plane, please refer to [Guide to design and creation of Data Plane REST API and Client Libraries](https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/591/Guide-to-design-and-creation-of-Data-Plane-REST-API-and-Client-Libraries); 
-
-For contribution access to spec repos, please refer to [Public repo vs. Private repo: To get write access](https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/202/Overall-Process-of-Management-Plane-SDK-Onboarding?anchor=2.-create/update-the-openapi-specifications%2C-and-launch-swagger-pr-review)
+[Create high-level Azure REST API design](https://eng.ms/docs/products/azure-developer-experience/design/api-design)
diff --git a/documentation/FAQ.md b/documentation/FAQ.md
@@ -1,20 +1,17 @@
 # FAQ in Swagger PR Review
 
-This page is intended to answer questions frequently asked during Azure Swagger PR review.
+This page is intended to answer questions frequently asked during Azure API spec PR review.
 
-1. [I am new to Swagger/OpenAPI, How should I start?](#Onboard)
+1. [I am new to API specs, where should I start?](#Onboard)
 2. [How to fix validation failure?](#validation)
-3. [How to generate SDK from Swagger?](#SDK)
+3. [How to generate SDK from API specs?](#SDK)
 4. [How to generate document](#doc)
 5. [How to generate swagger examples](#examplegen)
-6. [If need further help, who can we contact?](#contact)
 
-## How to onboard PR review Process?<a name="Onboard"></a>
-If you are new to Swagger/OpenAPI, you can refer to this [document](https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/80/Getting-started-with-OpenAPI-specifications)
+## How to onboard to API spec PR review Process?<a name="Onboard"></a>
+If you are new to API spec, you can refer to this [document](https://eng.ms/docs/products/azure-developer-experience/design/api-specs/api-specs#create-your-rest-api-definition)
 
-If you are new to Swagger PR review process, you can refer to this [flowchart](https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/212/Swagger-PR-Review)
-
-You can refer to this [document](https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/49/Request-Access-to-Azure-SDK-repos) to get read permission to submit PR.
+You can refer to this [document](https://eng.ms/docs/products/azure-developer-experience/onboard/access) to get read permission to submit PR.
 
 ## How to fix validation failure?<a name="validation"></a>
 | Validation | Description | How to fix |
@@ -30,16 +27,11 @@ You can refer to this [document](https://dev.azure.com/azure-sdk/internal/_wiki/
 Refer to [Document](https://aka.ms/ci-fix) for how to run these tools locally
 
 ## How to generate SDK from Swagger?<a name="SDK"></a>
-If you are working in the public repository,SDK generation is triggered as soon as your OpenAPI specification (a.k.a swagger) PR is created/committed/merged in to the azure-rest-api-specs repository.
-
-If you are working in the private repository, please refer to this [document](https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/81/Management-Plane-SDK-generation) to manually generate SDKs of different languages, including Python, Java, Go, C#, Js etc.
+Refer to this [document](https://eng.ms/docs/products/azure-developer-experience/develop/sdk-generate).
 
 
 ## How to generate Document from Swagger?<a name="doc"></a>
-Refer to [document](https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/79/Generation-of-docs-on-docs.microsoft.com)
+Refer to [document](https://eng.ms/docs/products/azure-developer-experience/design/api-docs)
 
 ## How to generate examples from Swagger?<a name="examplegen"></a>
-Refer to [Swagger-Example-Generation](https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/393/Swagger-Example-Generation)
-
-## If need further help, who can we contact?<a name="contact"></a>
-If any other help need, Please send a mail to vscswagger@microsoft.com
+Refer to [Swagger-Example-Generation](https://github.com/Azure/oav/blob/develop/documentation/example-generation.md)
diff --git a/documentation/ci-fix.md b/documentation/ci-fix.md
@@ -51,7 +51,7 @@ oav validate-example <swagger-spec-path>
 Please see [readme](https://github.com/Azure/oav/blob/bd04e228b4181c53769ed88e561dec5212e77253/README.md) for how to install or run tool in details.
 Or you can run it in [OpenAPI Hub](https://portal.azure-devex-tools.com/tools/static-validation/static/errors/default).
 Refer to [Semantic and Model Violations Reference](https://github.com/Azure/azure-rest-api-specs/blob/main/documentation/Semantic-and-Model-Violations-Reference.md) for detailed description of validations and how-to-fix guidance.
-Refer to [Swagger-Example-Generation](https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/393/Swagger-Example-Generation) for example automatic generation.
+Refer to [Swagger-Example-Generation](https://github.com/Azure/oav/blob/develop/documentation/example-generation.md) for example automatic generation.
 
 ## Semantic Validation
 
@@ -126,7 +126,7 @@ If you see `Swagger ApiDocPreview ` check fail with a failure [like this one](ht
 |-|-|
 | ❌ RestBuild error | "logUrl":"https://apidrop.visualstudio.com/Content%20CI/_build/results?buildId=373646&view=logs&j=fd490c07-0b22-5182-fac9-6d67fe1e939b",<br/>"detail":"Run.ps1 failed with exit code 1 " |
 
-Then refer to [this TSG](https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/79/Generation-of-docs-on-learn.microsoft.com?anchor=%22swagger-apidocpreview%22-build-is-failing).
+Refer to [troubleshoothing REST API documentation](https://eng.ms/docs/products/azure-developer-experience/design/api-docs-troubleshooting).
 
 ## TypeSpec Validation
 
diff --git a/documentation/onboard-dpg-in-sdkautomation/README.md b/documentation/onboard-dpg-in-sdkautomation/README.md
@@ -18,7 +18,7 @@ __Description:__
 2. If you have added a comment, which contains autorest configuration, and run `/azp run` in the spec PR, the autorest configuration in the comment will be used to generate SDK.
 Otherwise, pipeline will try to find autorest configuration file in sdk repository. If found, use the autorest configuration file to generate SDK. If not found, pipeline will stop.
    - Please refer to [Add autorest configuration in spec comment](./add-autorest-configuration-for-dataplane-sdk.md) on how to add autorest configuration in spec comment.
-3. SDK and ApiView will be generated in spec CI pipeline, and you can find them in spec PR comment. Please refer to the [Guide of Reviewing the Api Design/Definition](https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/591/Guide-to-design-and-creation-of-Data-Plane-REST-API-and-Client-Libraries?anchor=ii.-review-the-api-design/definition) to review the API definition.
+3. SDK and ApiView will be generated in spec CI pipeline, and you can find them in spec PR comment. Refer to the [Get your PR merged](https://eng.ms/docs/products/azure-developer-experience/design/api-specs-pr/api-specs-pr?tabs=dataplane) for next steps.
 4. If any change needed, please update the autorest configuration in spec PR comment and regenerate the SDK by adding a comment `/azp run` to swagger PR.
 
 ## FAQ
diff --git a/documentation/openapi-authoring-automated-guidelines.md b/documentation/openapi-authoring-automated-guidelines.md
@@ -20,7 +20,7 @@ We request OpenAPI(Swagger) spec authoring be assigned to engineers who have an
 * [Rule Descriptions](#rule-descriptions)
 
 ## Error vs Warning
-- Rules with severity "Error" have to be addressed for the OpenAPI(swagger) spec to be approved by the reviewers. If there is a strong reason for why the rule cannot be addressed in an OpenAPI(swagger) spec it will be a permanent exception, then [suppression process](https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/85/Swagger-Suppression-Process) must be followed.
+- Rules with severity "Error" have to be addressed for the OpenAPI(swagger) spec to be approved by the reviewers. If there is a strong reason for why the rule cannot be addressed in an OpenAPI(swagger) spec it will be a permanent exception, then [suppression process](https://aka.ms/pr-suppressions) must be followed.
 
 - Rules with severity "Warning" are either strong recommendations made by Azure developer experience team for better SDK/Documentation experience or they point out something to evaluate, for example, the warning for booleans asks the user to evaluate whether the property should be a boolean or not. 
 
@@ -3545,7 +3545,7 @@ Links: [Index](#index) | [Error vs. Warning](#error-vs-warning) | [Automated Rul
 
 **Output Message** : The parameters should be kept in the same order as they present in the path.
 
-**Description**: The rule is to ensure the parameters in the same order as they are ranked in the path. Since it can introduce a breaking change when updating parameter order, for services that have already shipped public versions, you may request to suppress the rule following the process documented here: https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/85/Swagger-Suppression-Process
+**Description**: The rule is to ensure the parameters in the same order as they are ranked in the path. Since it can introduce a breaking change when updating parameter order, for services that have already shipped public versions, you may request to suppress the rule following the process documented here: https://aka.ms/pr-suppressions
 
 **CreatedAt**: November 8, 2021
 
