Add info about `SDK azure-sdk-for-*` checks and `SDK azure-powershell` to `ci-fix` doc; Clean up markdownlint rules and `ci-fix` doc. (#29311)
This commit is contained in:
Konrad Jamrozik
GitHub
Родитель
ca620a2967
Коммит
67e8e173b7
|
|
@ -1,27 +0,0 @@
|
|||
{
|
||||
"default": true,
|
||||
"MD001": false,
|
||||
"MD003": false,
|
||||
"MD004": false,
|
||||
"MD005": false,
|
||||
"MD006": false,
|
||||
"MD007": false,
|
||||
"MD009": false,
|
||||
"MD012": false,
|
||||
"MD013": false,
|
||||
"MD020": false,
|
||||
"MD022": false,
|
||||
"MD024": false,
|
||||
"MD025": false,
|
||||
"MD026": false,
|
||||
"MD028": false,
|
||||
"MD029": false,
|
||||
"MD031": false,
|
||||
"MD032": false,
|
||||
"MD033": false,
|
||||
"MD034": false,
|
||||
"MD036": false,
|
||||
"MD040": false,
|
||||
"MD041": false,
|
||||
"MD047": false
|
||||
}
|
||||
|
|
@ -0,0 +1,35 @@
|
|||
{
|
||||
"default": true,
|
||||
|
||||
// MD013 - Line length
|
||||
// https://github.com/DavidAnson/markdownlint/blob/main/doc/md013.md
|
||||
//
|
||||
// "line_length" : 120:
|
||||
// Allow lines of length 120 instead of the default 80. Keep in sync with guide lines .vscode/settings.json.
|
||||
//
|
||||
// "tables": false
|
||||
// Do not include tables. Breaking a line in a table to meet the line length would add a line break in the table
|
||||
// itself. We do not want that.
|
||||
//
|
||||
// "headings": false
|
||||
// Do not include headings. One cannot break lines in headings, and we sometimes need long ones, e.g. for FAQs.
|
||||
"MD013": { "line_length" : 120, "tables": false, "headings": false },
|
||||
|
||||
// MD025 - Multiple top-level headings in the same document
|
||||
// https://github.com/DavidAnson/markdownlint/blob/main/doc/md025.md
|
||||
//
|
||||
// We sometimes prefer to have multiple top-level headings in the same document.
|
||||
"MD025": false,
|
||||
|
||||
// MD033 - No inline HTML
|
||||
// https://github.com/DavidAnson/markdownlint/blob/main/doc/md033.md
|
||||
//
|
||||
// We allow inline HTML as sometimes we need <br/> within table cells.
|
||||
"MD033": false,
|
||||
|
||||
// MD034 - Bare URL used
|
||||
// https://github.com/DavidAnson/markdownlint/blob/main/doc/md034.md
|
||||
//
|
||||
// We allow bare URLs e.g. to link to GitHub issues.
|
||||
"MD034": false
|
||||
}
|
||||
|
|
@ -31,5 +31,10 @@
|
|||
"[typespec]": {
|
||||
"editor.defaultFormatter": "typespec.typespec-vscode",
|
||||
"editor.formatOnSave": true
|
||||
}
|
||||
},
|
||||
"[markdown]": {
|
||||
"editor.rulers": [
|
||||
{ "column": 120, "color": "#ff0000c0" }
|
||||
]
|
||||
},
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,76 +1,253 @@
|
|||
# CI Fix Guide
|
||||
|
||||
Short link: [aka.ms/ci-fix]
|
||||
|
||||
This guide provides detailed troubleshooting instructions for the [automated validation tooling] checks running on
|
||||
[Azure REST API specs PR]s submitted to this repo.
|
||||
|
||||
If you need help with your specs PR, please first thoroughly read the [aka.ms/azsdk/pr-getting-help] document.
|
||||
|
||||
# Table of Contents
|
||||
|
||||
- [Table of Contents](#table-of-contents)
|
||||
- [CI Fix Guide](#ci-fix-guide)
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [`Swagger SpellCheck`](#swagger-spellcheck)
|
||||
- [`Swagger PrettierCheck`](#swagger-prettiercheck)
|
||||
- [Prettier reference](#prettier-reference)
|
||||
- [`Swagger ModelValidation`](#swagger-modelvalidation)
|
||||
- [`Swagger SemanticValidation`](#swagger-semanticvalidation)
|
||||
- [Table of Contents](#table-of-contents)
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Checks troubleshooting guides](#checks-troubleshooting-guides)
|
||||
- [`CredScan`](#credscan)
|
||||
- [`PoliCheck`](#policheck)
|
||||
- [`SDK azure-powershell`](#sdk-azure-powershell)
|
||||
- [`SDK azure-sdk-for-*` checks, like `SDK azure-sdk-for-go`](#sdk-azure-sdk-for--checks-like-sdk-azure-sdk-for-go)
|
||||
- [`Swagger APIView`](#swagger-apiview)
|
||||
- [If an expected APIView was not generated, follow the step below to troubleshoot.](#if-an-expected-apiview-was-not-generated-follow-the-step-below-to-troubleshoot)
|
||||
- [Diagnosing APIView failure for SDK Language (not Swagger or TypeSpec)](#diagnosing-apiview-failure-for-sdk-language-not-swagger-or-typespec)
|
||||
- [`Swagger ApiDocPreview`](#swagger-apidocpreview)
|
||||
- [`Swagger Avocado`](#swagger-avocado)
|
||||
- [Get help fixing Avocado validation failures](#get-help-fixing-avocado-validation-failures)
|
||||
- [Run avocado locally](#run-avocado-locally)
|
||||
- [`Swagger BreakingChange` and `BreakingChange(Cross-Version)`](#swagger-breakingchange-and-breakingchangecross-version)
|
||||
- [Adding label on PR automatically](#adding-label-on-pr-automatically)
|
||||
- [Run `oad` locally](#run-oad-locally)
|
||||
- [`Swagger LintDiff` and `Swagger Lint(RPaaS)`](#swagger-lintdiff-and-swagger-lintrpaas)
|
||||
- [`Swagger LintDiff` for TypeSpec: troubleshooting guides](#swagger-lintdiff-for-typespec-troubleshooting-guides)
|
||||
- [`Record<unkown>` causes `AvoidAdditionalProperties` and `PropertiesTypeObjectNoDefinition`](#recordunkown-causes-avoidadditionalproperties-and-propertiestypeobjectnodefinition)
|
||||
- [`Record<unknown>` causes `AvoidAdditionalProperties` and `PropertiesTypeObjectNoDefinition`](#recordunknown-causes-avoidadditionalproperties-and-propertiestypeobjectnodefinition)
|
||||
- [`RequestBodyMustExistForPutPatch`](#requestbodymustexistforputpatch)
|
||||
- [`PatchPropertiesCorrespondToPutProperties`](#patchpropertiescorrespondtoputproperties)
|
||||
- [`@singleton` causes `EvenSegmentedPathForPutOperation` and `XmsPageableForListCalls`](#singleton-causes-evensegmentedpathforputoperation-and-xmspageableforlistcalls)
|
||||
- [`AvoidAnonymousParameter`, `AvoidAnonymousTypes`, `IntegerTypeMustHaveFormat`](#avoidanonymousparameter-avoidanonymoustypes-integertypemusthaveformat)
|
||||
- [`AvoidAnonymousTypes` inside a 202 response](#avoidanonymoustypes-inside-a-202-response)
|
||||
- [`OAuth2Auth` causes `XmsEnumValidation`](#oauth2auth-causes-xmsenumvalidation)
|
||||
- [`Swagger Avocado`](#swagger-avocado)
|
||||
- [Get help fixing Avocado validation failures](#get-help-fixing-avocado-validation-failures)
|
||||
- [Run avocado locally](#run-avocado-locally)
|
||||
- [`Swagger ApiDocPreview`](#swagger-apidocpreview)
|
||||
- [`Swagger ModelValidation`](#swagger-modelvalidation)
|
||||
- [`Swagger PrettierCheck`](#swagger-prettiercheck)
|
||||
- [Prettier reference](#prettier-reference)
|
||||
- [`Swagger SemanticValidation`](#swagger-semanticvalidation)
|
||||
- [`Swagger SpellCheck`](#swagger-spellcheck)
|
||||
- [`TypeSpec Validation`](#typespec-validation)
|
||||
- [Run `tsv` locally](#run-tsv-locally)
|
||||
- [APIView Failures: troubleshooting guides](#apiview-failures-troubleshooting-guides)
|
||||
- [Suppression Process](#suppression-process)
|
||||
- [Checks not covered by this guide](#checks-not-covered-by-this-guide)
|
||||
- [Obsolete checks](#obsolete-checks)
|
||||
- [`license/cla`](#licensecla)
|
||||
- [Suppression Process](#suppression-process)
|
||||
- [Checks not covered by this guide](#checks-not-covered-by-this-guide)
|
||||
- [Obsolete checks](#obsolete-checks)
|
||||
|
||||
|
||||
# CI Fix Guide
|
||||
|
||||
Short link: https://aka.ms/azsdk/ci-fix
|
||||
|
||||
This page provides detailed instructions on how to diagnose, reproduce, fix and get help on various [automated validation tooling] failures on your [Azure REST API specs PR].
|
||||
|
||||
For more help, see [aka.ms/azsdk/pr-getting-help] and [aka.ms/azsdk/support].
|
||||
|
||||
## Prerequisites
|
||||
# Prerequisites
|
||||
|
||||
Most guides here require for you to have `npm` installed, which you can get by installing [Node.js](https://nodejs.org/en/download).
|
||||
|
||||
## `Swagger SpellCheck`
|
||||
# Checks troubleshooting guides
|
||||
|
||||
If you receive a spelling failure either fix the spelling to match or if there are words that need to be suppressed for your service then add the word to the override list in [cspell.json](https://github.com/Azure/azure-rest-api-specs/blob/main/cSpell.json). Either
|
||||
add to your existing section or create a new section for your specific spec or service family if the work is more generally used in lots of files under your service.
|
||||
## `CredScan`
|
||||
|
||||
This check is owned by One Engineering System. See [1ES CredScan] for help.
|
||||
|
||||
## `PoliCheck`
|
||||
|
||||
This check is owned by One Engineering System. See [1ES PoliCheck] for help.
|
||||
|
||||
## `SDK azure-powershell`
|
||||
|
||||
> [!IMPORTANT]
|
||||
>
|
||||
> - This check is never blocking merging of a spec PR, even if it fails.
|
||||
> - The `SDK azure-powershell` check is owned by the Shanghai division of the Azure SDK team,
|
||||
not the core Redmond Azure SDK team.
|
||||
|
||||
The owner of this check is Yeming Liu from the Shanghai division of the Azure SDK team.
|
||||
Please reach out to him with with any questions or concerns.
|
||||
|
||||
## `SDK azure-sdk-for-*` checks, like `SDK azure-sdk-for-go`
|
||||
|
||||
> [!IMPORTANT]
|
||||
>
|
||||
> - The `SDK azure-sdk-for-*` checks are owned by the Shanghai division of the Azure SDK team,
|
||||
not the core Redmond Azure SDK team.
|
||||
> - Only `SDK azure-sdk-for-go` check failure will block a specs PR, because this check serves as a canary for the
|
||||
entire `SDK azure-sdk-for-*` group of checks.
|
||||
|
||||
If you have an issue or with any of checks listed in the first column of the table below:
|
||||
|
||||
| Check name | Owner |
|
||||
|-----------------------------------|----------------|
|
||||
| `SDK azure-sdk-for-go` | Ray Chen |
|
||||
| `SDK azure-sdk-for-java` | Weidong Xu |
|
||||
| `SDK azure-sdk-for-js` | Qiaoqiao Zhang |
|
||||
| `SDK azure-sdk-for-net` | Wei Hu |
|
||||
| `SDK azure-sdk-for-net-track2` | Wei Hu |
|
||||
| `SDK azure-sdk-for-python` | Yuchao Yan |
|
||||
| `SDK azure-sdk-for-python-track2` | Yuchao Yan |
|
||||
|
||||
Do the following:
|
||||
|
||||
1. Attempt to diagnose the issue yourself:
|
||||
1. Look at the affected PR's `checks` tab for the failing check.
|
||||
1. Click on the `View Azure DevOps build log for more details.` link from that tab and inspect the devOps logs.
|
||||
For example, for `SDK azure-sdk-for-go` check look into the `SDK azure-sdk-fo-go` job, `SDK Automation` task logs.
|
||||
1. If your investigation denotes this is likely a bug in the check itself and not your PR, reach out
|
||||
to the owner of the check per the aforementioned table.
|
||||
|
||||
## `Swagger APIView`
|
||||
|
||||
Various APIViews are generated as part of the Azure REST API specs PR build. Among these are TypeSpec and Swagger as well as any other language that is being generated in the run. When everything is successful you should see a comment box similar to the picture below showing the APIViews generated for TypeSpec or Swagger, plus all other languages being generated.
|
||||
|
||||
|
||||
|
||||
### If an expected APIView was not generated, follow the step below to troubleshoot.
|
||||
|
||||
- On the CI check click on `details` > `View Azure DevOps build log for more details` to view the devOps logs.
|
||||
- Investigate the CI job for the languge with error. TypeSpec and Swagger APIViews are generated as part of the `AzureRestApiSpecsPipeline` stage in the `TypeSpecAPIView` and `SwaggerAPIView` jobs respectively, while APIViews for other SDK languges are generated in their respective language jobs in the `SDK Automation` stage.
|
||||
- Ensure that all previous checks in the job are green before proceeding.
|
||||
|
||||
### Diagnosing APIView failure for SDK Language (not Swagger or TypeSpec)
|
||||
|
||||
1. Check for an unexpected skip of the `Publish SDK APIView Artifact to Pipeline Artifacts` and `Generate SDK APIView` step.
|
||||
2. Look in `SDK Automation` step to verify that the API token generation completed successfully.
|
||||
3. Search logs for `Read Temp File`
|
||||
4. Below `Read Temp File` find the .json object and search within to locate the `apiViewArtifact` property.
|
||||
5. If not present, the APIView parser for the language failed to generate the `APIView Token Artifacts`.
|
||||
6. Please contact [APIView Support Teams Channel] for assistance.
|
||||
|
||||
## `Swagger ApiDocPreview`
|
||||
|
||||
If you see `Swagger ApiDocPreview` check fail with a failure [like this one](https://github.com/Azure/azure-rest-api-specs/pull/24841/checks?check_run_id=15056283615):
|
||||
|
||||
| Rule | Message |
|
||||
|-|-|
|
||||
| ❌ 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 " |
|
||||
|
||||
Refer to [troubleshooting REST API documentation](https://eng.ms/docs/products/azure-developer-experience/design/api-docs-troubleshooting).
|
||||
|
||||
## `Swagger Avocado`
|
||||
|
||||
> [!IMPORTANT]
|
||||
> `Swagger Avocado` check is not a blocking for merging your PR, even if it fails.
|
||||
> It is left to the discretion of the PR reviewer if the Avocado failure actually
|
||||
> needs to be addressed or suppressed.
|
||||
|
||||
### Get help fixing Avocado validation failures
|
||||
|
||||
Refer to [Avocado README](https://github.com/Azure/avocado/blob/master/README.md) for detailed description of validations and how-to-fix guidance.
|
||||
|
||||
### Run avocado locally
|
||||
|
||||
``` powershell
|
||||
npm install -g @azure/avocado
|
||||
|
||||
avocado
|
||||
```
|
||||
"overrides": [
|
||||
... example of specific file override
|
||||
{
|
||||
"filename": "**/specification/hdinsight/resource-manager/Microsoft.HDInsight/preview/2015-03-01-preview/cluster.json",
|
||||
"words": [
|
||||
"saskey"
|
||||
]
|
||||
}
|
||||
... example of specific service family override
|
||||
{
|
||||
"filename": "**/specification/cognitiveservices/**/*.json",
|
||||
"words": [
|
||||
"flac",
|
||||
"mpga"
|
||||
]
|
||||
}
|
||||
|
||||
When type avocado in command line, avocado will validate in the current directory.
|
||||
|
||||
Note: When running in OpenAPI spec PR pipeline, Avocado only report errors with file updates in the PR, but ignore the errors existing in base. However when running Avocado against local directory, it reports all errors existing in the files.
|
||||
|
||||
- Run all specs: Clone the repo `azure/azure-rest-api-specs` and run "avocado" in folder `azure/azure-rest-api-specs`.
|
||||
- Run single service specs: create a folder `specification`. and move your service specs folder in `specification`. run "avocado"
|
||||
|
||||
## `Swagger BreakingChange` and `BreakingChange(Cross-Version)`
|
||||
|
||||
See [aka.ms/azsdk/pr-brch-deep](https://aka.ms/azsdk/pr-brch-deep). If you want a quick read, see only [the `summary` section](https://aka.ms/azsdk/pr-brch-deep#summary).
|
||||
|
||||
### Run `oad` locally
|
||||
|
||||
To repro issues with "breaking changes" checks, you can locally run the tool that powers them: [Azure/openapi-diff](https://github.com/Azure/openapi-diff), aka `oad`:
|
||||
|
||||
``` powershell
|
||||
npm install -g @azure/oad
|
||||
oad compare <old-spec-path> <new-spec-path>
|
||||
```
|
||||
Words are case-insensitive so use lower case for the word list.
|
||||
|
||||
If you need more information on see [cspell configuration](https://cspell.org/configuration/).
|
||||
Please see [readme](https://github.com/Azure/openapi-diff/blob/main/README.md) for how to install or run tool in details.
|
||||
Refer to [Oad Docs](https://github.com/Azure/openapi-diff/tree/main/docs) for detailed description of all oad rules.
|
||||
|
||||
*Note*: We are trying to move away from one shared dictionary file so try and avoid editing custom-words.txt in the root as it will likely go away in the future.
|
||||
|
||||
## `Swagger LintDiff` and `Swagger Lint(RPaaS)`
|
||||
|
||||
The [LintDiff validation tool](https://github.com/Azure/azure-openapi-validator) runs linting rules against specification difference. Two specifications are compared: the specification as it would be when proposed PR is merged, vs the specification as seen before the PR is merged.
|
||||
|
||||
Refer to [openapi-authoring-automated-guidelines](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/openapi-authoring-automated-guidelines.md) for detailed description of all lint rules and how-to-fix guidance.
|
||||
If that guidance is not enough, please also refer to the [LintDiff rules.md doc](https://github.com/Azure/azure-openapi-validator/blob/main/docs/rules.md). It links to `.md` files related to given error, containing instructions how to fix them.
|
||||
|
||||
To reproduce LintDiff failures locally, see [CONTRIBUTING.md / How to locally reproduce a LintDiff failure occurring on a PR](https://github.com/Azure/azure-openapi-validator/blob/main/CONTRIBUTING.md#how-to-locally-reproduce-a-lintdiff-failure-occurring-on-a-pr).
|
||||
|
||||
## `Swagger LintDiff` for TypeSpec: troubleshooting guides
|
||||
|
||||
Check `Swagger LintDiff` may fail for the OpenAPI generated from TypeSpec, even if there are no warnings or errors reported from the TypeSpec compiler. Causes include bugs in the TypeSpec OpenAPI emitter, bugs in LintDiff rules, incompatibilities between TypeSpec and LintDiff, or checks duplicated in TypeSpec and LintDiff.
|
||||
|
||||
We are working to address the root causes (where possible). Until then, we recommend you [suppress](#suppression-process) these LintDiff errors, using a "permanent suppression" with a descriptive "reason", so we can revert your suppression when the root cause is fixed.
|
||||
|
||||
### `Record<unknown>` causes `AvoidAdditionalProperties` and `PropertiesTypeObjectNoDefinition`
|
||||
|
||||
The use of `Record<unknown>` in TypeSpec is discouraged, and there is a TypeSpec lint rule to enforce this. If you still need to use `Record<unknown>`, the OpenAPI spec generated will cause many LintDiff errors of types `AvoidAdditionalProperties` and `PropertiesTypeObjectNoDefinition`. You will need to suppress both the TypeSpec violation (in TypeSpec source code) and the LintDiff violations.
|
||||
|
||||
### `RequestBodyMustExistForPutPatch`
|
||||
|
||||
We believe this is a false positive: https://github.com/Azure/azure-openapi-validator/issues/641
|
||||
|
||||
### `PatchPropertiesCorrespondToPutProperties`
|
||||
|
||||
We believe this is a false positive: https://github.com/Azure/azure-openapi-validator/issues/642
|
||||
|
||||
### `@singleton` causes `EvenSegmentedPathForPutOperation` and `XmsPageableForListCalls`
|
||||
|
||||
If `EvenSegmentedPathForPutOperation` and/or `XmsPageableForListCalls` are failing for OpenAPI generated from TypeSpec using `@singleton` (OpenAPI path ends with `/default`), we believe this is a false positive: https://github.com/Azure/azure-openapi-validator/issues/646
|
||||
|
||||
### `AvoidAnonymousParameter`, `AvoidAnonymousTypes`, `IntegerTypeMustHaveFormat`
|
||||
|
||||
Data-plane specs can suppress violations of the following rules, since they only exist for the benefit of SDKs generated from swagger, and data-plane SDKs are generated directly from TypeSpec. Resource-manager specs should **not** suppress violations of these rules, since resource-manager SDKs are generated from OpenAPI, and rely on these errors being fixed.
|
||||
|
||||
- `AvoidAnonymousParameter`
|
||||
- `AvoidAnonymousTypes`
|
||||
- `IntegerTypeMustHaveFormat`
|
||||
|
||||
### `AvoidAnonymousTypes` inside a 202 response
|
||||
|
||||
As an exception to the previous note, resource-manager specs **may** be able to suppress `AvoidAnonymousTypes`, but only if the error is inside a 202 response from a long-running operation (LRO). It is known that SDKs do not need to generate type names for such responses.
|
||||
|
||||
### `OAuth2Auth` causes `XmsEnumValidation`
|
||||
|
||||
TypeSpec using `OAuth2Auth` may generate the following OpenAPI:
|
||||
|
||||
``` yaml
|
||||
"type": {
|
||||
"type": "string",
|
||||
"description": "OAuth2 authentication",
|
||||
"enum": [
|
||||
"oauth2"
|
||||
]
|
||||
},
|
||||
```
|
||||
|
||||
Which causes error `XmsEnumValidation`. The recommended workaround is to add `omit-unreachable-types: true` to your `tspconfig.yaml`.
|
||||
|
||||
## `Swagger ModelValidation`
|
||||
|
||||
To repro issues with `Swagger ModelValidation` locally:
|
||||
|
||||
``` powershell
|
||||
npm install -g oav
|
||||
oav validate-example <openapi-spec-path>
|
||||
```
|
||||
|
||||
Please see [readme](https://github.com/Azure/oav/blob/bd04e228b4181c53769ed88e561dec5212e77253/README.md) for how to install or run tool in details.
|
||||
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://github.com/Azure/oav/blob/develop/documentation/example-generation.md) for example automatic generation.
|
||||
|
||||
## `Swagger PrettierCheck`
|
||||
|
||||
|
|
@ -78,7 +255,7 @@ First, ensure you have fulfilled `Prerequisites` as explained above.
|
|||
|
||||
To update all the spec files for a given service run the following:
|
||||
|
||||
```
|
||||
``` powershell
|
||||
# To fix all the files in the repo run from the root of the repo
|
||||
cd <local_repo_clone_root>
|
||||
|
||||
|
|
@ -99,139 +276,51 @@ Then please commit and push changes made by prettier.
|
|||
|
||||
### Prettier reference
|
||||
|
||||
- [`prettier` npm package](https://www.npmjs.com/package/prettier).
|
||||
- [`prettier` npm package](https://www.npmjs.com/package/prettier)
|
||||
- [Source: Swagger-Prettier-Check.ps1](https://github.com/Azure/azure-rest-api-specs/blob/main/eng/scripts/Swagger-Prettier-Check.ps1)
|
||||
- [Pipeline: Swagger PrettierCheck](https://dev.azure.com/azure-sdk/public/_build?definitionId=6405)
|
||||
|
||||
## `Swagger ModelValidation`
|
||||
|
||||
To repro issues with `Swagger ModelValidation` locally:
|
||||
```
|
||||
npm install -g oav
|
||||
oav validate-example <openapi-spec-path>
|
||||
```
|
||||
Please see [readme](https://github.com/Azure/oav/blob/bd04e228b4181c53769ed88e561dec5212e77253/README.md) for how to install or run tool in details.
|
||||
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://github.com/Azure/oav/blob/develop/documentation/example-generation.md) for example automatic generation.
|
||||
|
||||
## `Swagger SemanticValidation`
|
||||
|
||||
To repro issues with `Swagger SemanticValidation` locally:
|
||||
```
|
||||
|
||||
``` powershell
|
||||
npm install -g oav
|
||||
oav validate-spec <openapi-spec-path>
|
||||
```
|
||||
|
||||
Please see [readme](https://github.com/Azure/oav/blob/bd04e228b4181c53769ed88e561dec5212e77253/README.md) for how to install or run tool in details.
|
||||
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.
|
||||
|
||||
## `Swagger BreakingChange` and `BreakingChange(Cross-Version)`
|
||||
## `Swagger SpellCheck`
|
||||
|
||||
See [aka.ms/azsdk/pr-brch-deep](https://aka.ms/azsdk/pr-brch-deep). If you want a quick read, see only [the `summary` section](https://aka.ms/azsdk/pr-brch-deep#summary).
|
||||
If you receive a spelling failure either fix the spelling to match or if there are words that need to be suppressed for your service then add the word to the override list in [cspell.json](https://github.com/Azure/azure-rest-api-specs/blob/main/cSpell.json). Either
|
||||
add to your existing section or create a new section for your specific spec or service family if the work is more generally used in lots of files under your service.
|
||||
|
||||
### Run `oad` locally
|
||||
|
||||
To repro issues with "breaking changes" checks, you can locally run the tool that powers them: [Azure/openapi-diff](https://github.com/Azure/openapi-diff), aka `oad`:
|
||||
```
|
||||
npm install -g @azure/oad
|
||||
oad compare <old-spec-path> <new-spec-path>
|
||||
```
|
||||
Please see [readme](https://github.com/Azure/openapi-diff/blob/main/README.md) for how to install or run tool in details.
|
||||
Refer to [Oad Docs](https://github.com/Azure/openapi-diff/tree/main/docs) for detailed description of all oad rules.
|
||||
|
||||
## `Swagger LintDiff` and `Swagger Lint(RPaaS)`
|
||||
|
||||
The [LintDiff validation tool](https://github.com/Azure/azure-openapi-validator) runs linting rules against specification difference. Two specifications are compared: the specification as it would be when proposed PR is merged, vs the specification as seen before the PR is merged.
|
||||
|
||||
Refer to [openapi-authoring-automated-guidelines](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/openapi-authoring-automated-guidelines.md) for detailed description of all lint rules and how-to-fix guidance.
|
||||
If that guidance is not enough, please also refer to the [LintDiff rules.md doc](https://github.com/Azure/azure-openapi-validator/blob/main/docs/rules.md). It links to `.md` files related to given error, containing instructions how to fix them.
|
||||
|
||||
To reproduce LintDiff failures locally, see [CONTRIBUTING.md / How to locally reproduce a LintDiff failure occurring on a PR](https://github.com/Azure/azure-openapi-validator/blob/main/CONTRIBUTING.md#how-to-locally-reproduce-a-lintdiff-failure-occurring-on-a-pr).
|
||||
|
||||
## `Swagger LintDiff` for TypeSpec: troubleshooting guides
|
||||
|
||||
Check `Swagger LintDiff` may fail for the OpenAPI generated from TypeSpec, even if there are no warnings or errors reported from the TypeSpec compiler. Causes include bugs in the TypeSpec OpenAPI emitter, bugs in LintDiff rules, incompatibilities between TypeSpec and LintDiff, or checks duplicated in TypeSpec and LintDiff.
|
||||
|
||||
We are working to address the root causes (where possible). Until then, we recommend you [suppress](#suppression-process) these LintDiff errors, using a "permanent suppression" with a descriptive "reason", so we can revert your suppression when the root cause is fixed.
|
||||
|
||||
### `Record<unkown>` causes `AvoidAdditionalProperties` and `PropertiesTypeObjectNoDefinition`
|
||||
|
||||
The use of `Record<unkown>` in TypeSpec is discouraged, and there is a TypeSpec lint rule to enforce this. If you still need to use `Record<unknown>`, the OpenAPI spec generated will cause many LintDiff errors of types `AvoidAdditionalProperties` and `PropertiesTypeObjectNoDefinition`. You will need to suppress both the TypeSpec violation (in TypeSpec source code) and the LintDiff violations.
|
||||
|
||||
### `RequestBodyMustExistForPutPatch`
|
||||
|
||||
We believe this is a false positive: https://github.com/Azure/azure-openapi-validator/issues/641
|
||||
|
||||
### `PatchPropertiesCorrespondToPutProperties`
|
||||
|
||||
We believe this is a false positive: https://github.com/Azure/azure-openapi-validator/issues/642
|
||||
|
||||
### `@singleton` causes `EvenSegmentedPathForPutOperation` and `XmsPageableForListCalls`
|
||||
|
||||
If `EvenSegmentedPathForPutOperation` and/or `XmsPageableForListCalls` are failing for OpenAPI generated from TypeSpec using `@singleton` (OpenAPI path ends with `/default`), we believe this is a false positive: https://github.com/Azure/azure-openapi-validator/issues/646
|
||||
|
||||
### `AvoidAnonymousParameter`, `AvoidAnonymousTypes`, `IntegerTypeMustHaveFormat`
|
||||
|
||||
Data-plane specs can suppress violations of the following rules, since they only exist for the benefit of SDKs generated from swagger, and data-plane SDKs are generated directly from TypeSpec. Resource-manager specs should **not** suppress violations of these rules, since resource-manager SDKs are generated from OpenAPI, and rely on these errors being fixed.
|
||||
|
||||
* `AvoidAnonymousParameter`
|
||||
* `AvoidAnonymousTypes`
|
||||
* `IntegerTypeMustHaveFormat`
|
||||
|
||||
### `AvoidAnonymousTypes` inside a 202 response
|
||||
|
||||
As an exception to the previous note, resource-manager specs **may** be able to suppress `AvoidAnonymousTypes`, but only if the error is inside a 202 response from a long-running operation (LRO). It is known that SDKs do not need to generate type names for such responses.
|
||||
|
||||
### `OAuth2Auth` causes `XmsEnumValidation`
|
||||
|
||||
TypeSpec using `OAuth2Auth` may generate the following OpenAPI:
|
||||
|
||||
```
|
||||
"type": {
|
||||
"type": "string",
|
||||
"description": "OAuth2 authentication",
|
||||
"enum": [
|
||||
"oauth2"
|
||||
]
|
||||
},
|
||||
``` yaml
|
||||
"overrides": [
|
||||
... example of specific file override
|
||||
{
|
||||
"filename": "**/specification/hdinsight/resource-manager/Microsoft.HDInsight/preview/2015-03-01-preview/cluster.json",
|
||||
"words": [
|
||||
"saskey"
|
||||
]
|
||||
}
|
||||
... example of specific service family override
|
||||
{
|
||||
"filename": "**/specification/cognitiveservices/**/*.json",
|
||||
"words": [
|
||||
"flac",
|
||||
"mpga"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Which causes error `XmsEnumValidation`. The recommended workaround is to add `omit-unreachable-types: true` to your `tspconfig.yaml`.
|
||||
Words are case-insensitive so use lower case for the word list.
|
||||
|
||||
## `Swagger Avocado`
|
||||
If you need more information on see [cspell configuration](https://cspell.org/configuration/).
|
||||
|
||||
>[!IMPORTANT]
|
||||
> `Swagger Avocado` check is not a blocking for merging your PR, even if it fails.
|
||||
> It is left to the discretion of the PR reviewer if the Avocado failure actually
|
||||
> needs to be addressed or suppressed.
|
||||
|
||||
### Get help fixing Avocado validation failures
|
||||
|
||||
Refer to [Avocado README](https://github.com/Azure/avocado/blob/master/README.md) for detailed description of validations and how-to-fix guidance.
|
||||
|
||||
### Run avocado locally
|
||||
|
||||
```
|
||||
npm install -g @azure/avocado
|
||||
|
||||
avocado
|
||||
```
|
||||
|
||||
When type avocado in command line, avocado will validate in the current directory.
|
||||
|
||||
Note: When running in OpenAPI spec PR pipeline, Avocado only report errors with file updates in the PR, but ignore the errors existing in base. However when running Avocado against local directory, it reports all errors existing in the files.
|
||||
|
||||
- Run all specs: Clone the repo `azure/azure-rest-api-specs` and run "avocado" in folder `azure/azure-rest-api-specs`.
|
||||
- Run single service specs: create a folder `specification`. and move your service specs folder in `specification`. run "avocado"
|
||||
|
||||
## `Swagger ApiDocPreview`
|
||||
|
||||
If you see `Swagger ApiDocPreview ` check fail with a failure [like this one](https://github.com/Azure/azure-rest-api-specs/pull/24841/checks?check_run_id=15056283615):
|
||||
|
||||
| Rule | Message |
|
||||
|-|-|
|
||||
| ❌ 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 " |
|
||||
|
||||
Refer to [troubleshooting REST API documentation](https://eng.ms/docs/products/azure-developer-experience/design/api-docs-troubleshooting).
|
||||
*Note*: We are trying to move away from one shared dictionary file so try and avoid editing custom-words.txt in the root as it will likely go away in the future.
|
||||
|
||||
## `TypeSpec Validation`
|
||||
|
||||
|
|
@ -239,7 +328,7 @@ This validator will help ensure your TypeSpec project follows [standard conventi
|
|||
|
||||
### Run `tsv` locally
|
||||
|
||||
```
|
||||
``` powershell
|
||||
cd <repo>
|
||||
git checkout <your-branch>
|
||||
git merge <target-branch>
|
||||
|
|
@ -247,43 +336,31 @@ npm ci
|
|||
npx tsv <path-to-your-spec>
|
||||
git commit; git push (if any changes)
|
||||
|
||||
# example
|
||||
# example
|
||||
npx tsv specification/contosowidgetmanager/Contoso.WidgetManager
|
||||
```
|
||||
|
||||
Then check any errors that might be outputted and address any issues as needed. If there are changed files after the runit generally means
|
||||
that the generated OpenAPI spec files were not in-sync with the TypeSpec project and you should include those changes in your pull request as well.
|
||||
that the generated OpenAPI spec files were not in-sync with the TypeSpec project and you should include those changes in your pull request as well.
|
||||
|
||||
If none of the above helped, please reach out on [TypeSpec Discussions Teams channel].
|
||||
|
||||
## APIView Failures: troubleshooting guides
|
||||
Various APIViews are generated as part of the Azure REST API specs PR build. Among these are TypeSpec and Swagger as well as any other language that is being generated in the run. When everything is successful you should see a comment box similar to the picture below showing the APIViews generated for TypeSpec or Swagger, plus all other languages being generated.
|
||||
## `license/cla`
|
||||
|
||||
|
||||
This check is owned by One Engineering System. See [1ES GitHub inside Microsoft] for help.
|
||||
|
||||
#### If an expected APIView was not generated, follow the step below to troubleshoot.
|
||||
# Suppression Process
|
||||
|
||||
- On the CI check click on `details` > `View Azure DevOps build log for more details` to view the devOps logs.
|
||||
- Investigate the CI job for the languge with error. TypeSpec and Swagger APIViews are generated as part of the `AzureRestApiSpecsPipeline` stage in the `TypeSpecAPIView` and `SwaggerAPIView` jobs respectively, while APIViews for other SDK languges are generated in their respective language jobs in the `SDK Automation` stage.
|
||||
- Ensure that all previous checks in the job are green before proceeding.
|
||||
In case there are validation errors reported against your service that you believe do not apply,
|
||||
we have a suppression process you can follow to permanently remove these reported errors for your specs.
|
||||
Refer to the [suppression guide](https://aka.ms/pr-suppressions) for detailed guidance.
|
||||
|
||||
#### Diagnosing APIView failure for SDK Language (not Swagger or TypeSpec)
|
||||
1. Check for an unexpected skip of the `Publish SDK APIView Artifact to Pipeline Artifacts` and `Generate SDK APIView` step.
|
||||
2. Look in `SDK Automation` step to verify that the API token generation completed successfully.
|
||||
3. Search logs for `Read Temp File`
|
||||
4. Below `Read Temp File` find the .json object and search within to locate the `apiViewArtifact` property.
|
||||
5. If not present, the APIView parser for the language failed to generate the `APIView Token Artifacts`.
|
||||
6. Please contact [APIView Support Teams Channel] for assistance.
|
||||
# Checks not covered by this guide
|
||||
|
||||
## Suppression Process
|
||||
If you have an issue with a check that is not covered by this guide and the help at [aka.ms/azsdk/pr-getting-help],
|
||||
see [aka.ms/azsdk/support].
|
||||
|
||||
In case there are validation errors reported against your service that you believe do not apply, we have a suppression process you can follow to permanently remove these reported errors for your specs. Refer to the [suppression guide](https://aka.ms/pr-suppressions) for detailed guidance.
|
||||
|
||||
## Checks not covered by this guide
|
||||
|
||||
If you have an issue with a check that is not covered by this guide and the help at [aka.ms/azsdk/pr-getting-help] is not enough,
|
||||
please reach out on the Teams channel: [aka.ms/azsdk/support/specreview-channel].
|
||||
|
||||
## Obsolete checks
|
||||
# Obsolete checks
|
||||
|
||||
Following checks have been removed from the validation toolchain as of August 2023.
|
||||
|
||||
|
|
@ -291,10 +368,13 @@ Following checks have been removed from the validation toolchain as of August 20
|
|||
- Service API Readiness Test
|
||||
- Traffic validation
|
||||
|
||||
[1ES CredScan]: https://eng.ms/docs/cloud-ai-platform/devdiv/one-engineering-system-1es/1es-docs/1es-pipeline-templates/features/sdlanalysis/credscan
|
||||
[1ES GitHub inside Microsoft]: https://eng.ms/docs/more/github-inside-microsoft/policies/cla
|
||||
[1ES PoliCheck]: https://eng.ms/docs/cloud-ai-platform/devdiv/one-engineering-system-1es/1es-docs/1es-pipeline-templates/features/sdlanalysis/policheck
|
||||
[aka.ms/azsdk/pr-getting-help]: https://aka.ms/azsdk/pr-getting-help
|
||||
[aka.ms/azsdk/support]: https://aka.ms/azsdk/support
|
||||
[aka.ms/ci-fix]: https://aka.ms/ci-fix
|
||||
[APIView Support Teams Channel]: https://teams.microsoft.com/l/channel/19%3A3adeba4aa1164f1c889e148b1b3e3ddd%40thread.skype/APIView?groupId=3e17dcb0-4257-4a30-b843-77f47f1d4121&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47
|
||||
[automated validation tooling]: https://eng.ms/docs/products/azure-developer-experience/design/api-specs/api-tooling
|
||||
[Azure REST API specs PR]: https://eng.ms/docs/products/azure-developer-experience/design/api-specs-pr/api-specs-pr
|
||||
[aka.ms/azsdk/pr-getting-help]: https://aka.ms/azsdk/pr-getting-help
|
||||
[aka.ms/azsdk/support/specreview-channel]: https://aka.ms/azsdk/support/specreview-channel
|
||||
[aka.ms/azsdk/support]: https://aka.ms/azsdk/support
|
||||
[TypeSpec Discussions Teams channel]: https://teams.microsoft.com/l/channel/19%3A906c1efbbec54dc8949ac736633e6bdf%40thread.skype/TypeSpec%20Discussion%20%F0%9F%90%AE?groupId=3e17dcb0-4257-4a30-b843-77f47f1d4121&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47
|
||||
[APIView Support Teams Channel]: https://teams.microsoft.com/l/channel/19%3A3adeba4aa1164f1c889e148b1b3e3ddd%40thread.skype/APIView?groupId=3e17dcb0-4257-4a30-b843-77f47f1d4121&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче