This page is intended to answer questions frequently asked during Azure Swagger PR review.
- I am new to Swagger/OpenAPI, How should I start?
- How to fix validation failure?
- How to generate SDK from Swagger?
- How to generate document
- How to generate swagger examples
- If need further help, who can we contact?
If you are new to Swagger/OpenAPI, you can refer to this document
If you are new to Swagger PR review process, you can refer to this flowchart
You can refer to this document to get read permission to submit PR.
| Validation | Description | How to fix |
|---|---|---|
| Model Validation | Model validation enforces correctness between example and swagger. It checks whether definitions for request parameters and responses, match an expected input/output payload of the service. | Here |
| Lint diff | A tool to check whether changes in PR are satisfied with certain kind of rules outlined in the automated rules checklist | Here |
| Breaking Change | A tool to check what a swagger PR has changed and whether these changes violate breaking changes rules. | Here |
| Avocado | Avocado validates folder structure and configuration. | Here |
| Semantic | Semantic validation enforces correctness on the swagger specific elements. Such as paths and operations. Ensure the element definition meet the OpenApi 2.0 specification. | Here |
| Prettier | Code formatter for Swagger | Here |
| BranchProtectionForPrivateRepo | BranchProtectionForPrivateRepo is designed to always fail to prevent from merging PR into master which is not allow in private swagger repo as it will cause issue to sync up from public repo. | You can ignore this failure |
Refer to Document for how to run these tools locally
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 to manually generate SDKs of different languages, including Python, Java, Go, C#, Js etc.
Refer to document
Refer to Swagger-Example-Generation
If any other help need, Please send a mail to vscswagger@microsoft.com