Short link: aka.ms/ci-fix

This guide provides detailed troubleshooting instructions for the automated validation tooling checks running on Azure REST API specs PRs submitted to this repo.

If you need help with your specs PR, please first thoroughly read the aka.ms/azsdk/pr-getting-help document.

• CI Fix Guide
• Table of Contents
• Prerequisites
• Checks troubleshooting guides
  • CredScan
  • PoliCheck
  • SDK Validation * checks, like SDK Validation - Go
  • SDK Breaking Change Review
  • Swagger APIView
    • If an expected APIView was not generated, follow the step below to troubleshoot.
    • Diagnosing APIView failure for SDK Language (not Swagger or TypeSpec)
  • Swagger ApiDocPreview
  • Swagger Avocado
  • Swagger BreakingChange and BreakingChange(Cross-Version)
    • Run oad locally
  • Swagger LintDiff and Swagger Lint(RPaaS)
  • Swagger LintDiff for TypeSpec: troubleshooting guides
  • Swagger ModelValidation
  • Swagger PrettierCheck
    • Prettier reference
  • Swagger SemanticValidation
  • Spell Check
  • TypeSpec Validation
  • license/cla
• Suppression Process
• Checks not covered by this guide
• Obsolete checks

Most guides here require for you to have npm installed, which you can get by installing Node.js.

This check is owned by One Engineering System. See 1ES CredScan for help.

This check is owned by One Engineering System. See 1ES PoliCheck for help.

If you have an issue or with any of checks listed in the first column of the table below:

Do the following:

1. Attempt to diagnose the issue yourself:
   1. Look at the affected PR's checks tab for the failing check.
   2. Click on the View more details on Azure Pipelines. link from that tab and inspect the devOps logs. For example, for SDK Validation - Go check look into the Azure Pipelines/SDK Validation - Go pipeline run logs.
2. 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.

If the SDK breaking changes haven't been reviewed after two additional business days, you may reach out to the reviewers:

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.

• 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 language 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 languages are generated in their respective language jobs in the SDK Automation stage.
• Ensure that all previous checks in the job are green before proceeding.

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.

If you see Swagger ApiDocPreview check fail with a failure like this one:

Refer to troubleshooting REST API documentation.

Moved to https://github.com/Azure/azure-rest-api-specs/wiki/Swagger-Avocado

See aka.ms/azsdk/pr-brch-deep. If you want a quick read, see only the summary section.

To repro issues with "breaking changes" checks, you can locally run the tool that powers them: Azure/openapi-diff, aka oad:

npm install -g @azure/oad
oad compare <old-spec-path> <new-spec-path>

Please see readme for how to install or run tool in details. Refer to Oad Docs for detailed description of all oad rules.

The LintDiff validation tool 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 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. 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-rest-api-specs/wiki/Swagger-LintDiff-for-TypeSpec

To repro issues with Swagger ModelValidation locally:

npm install -g oav
oav validate-example <openapi-spec-path>

Please see readme for how to install or run tool in details. Refer to Semantic and Model Violations Reference for detailed description of validations and how-to-fix guidance. Refer to Swagger-Example-Generation for example automatic generation.

First, ensure you have fulfilled Prerequisites as explained above.

To update all the spec files for a given service run the following:

# To fix all the files in the repo run from the root of the repo
cd <local_repo_clone_root>

# OPTIONAL STEP: To fix a particular service OpenAPI spec cd to that directory like
cd specification/contosowidgetmanager

# Install the dependencies to the local 'node_modules' folder.
npm install

# Run 'prettier --check' to verify the problems can be reproduced locally
npx prettier --check **/*.json

# Run 'prettier --write' to fix the problems.
npx prettier --write **/*.json

Then please commit and push changes made by prettier.

• prettier npm package
• Source: Swagger-Prettier-Check.ps1
• Pipeline: Swagger PrettierCheck

To repro issues with Swagger SemanticValidation locally:

npm install -g oav
oav validate-spec <openapi-spec-path>

Please see readme for how to install or run tool in details. Refer to Semantic and Model Violations Reference for detailed description of validations and how-to-fix guidance.

If you receive a spelling failure, first try to fix the spelling in source.

If there are new words that need to be supported for your service, add the word to the override list in the words list in the specification/<service>/cspell.yaml file for your service. Specific files can also be overridden using the override field in your service's cspell.yaml file (see example below).

If the specification/<service>/cspell.yaml file does not exist, create it using the example below and set the words and overrides fields to the words that need to be suppressed. The import field is required.

For example (note the words list is sorted alphabetically):

import:
  - ../../cspell.yaml
words:
  - aardvark
  - zoology

# Optional overrides example for words in a specific file
overrides: 
  - filename: '**/specification/contosowidgetmanager/somefile.yaml'
    words:
      - aardwolf
      - zoo

Spell checking is case-insensitive so you only need to add a word once in lower-case. Try to kept the word list sorted for easier discovery.

For more information see cspell configuration.

https://github.com/Azure/azure-rest-api-specs/wiki/TypeSpec-Validation

This check is owned by One Engineering System. See 1ES GitHub inside Microsoft for help.

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 for detailed guidance.

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.

Following checks have been removed from the validation toolchain as of August 2023.

• API Readiness Check
• Service API Readiness Test
• Traffic validation