This checklist is a current snapshot of requirements for developing Swagger specifications. The checklist will be continuously updated to reflect issues uncovered during Swagger specification reviews.
- Automated Rules of Checklist - Azure developer experience team is continuously working on automating as many rules as possible. Running the validation tools will give you these validation errors.
- Manual Rules of Checklist - These rules cannot be automated. They must be verified by service team and code reviewers manually.
Today, there are tools available for validating a sizable portion of this checklist. Please install these tools on your development machine and use them to validate your Swaggers as you build them.
-
AutoRest Linter – Linter statically analyzes a Swagger for errors and violations of requirements outlined in this checklist. Linter should be run when Swaggers are created or updated. Linter will be continously updated to validate newer requirements. NOTE: This checkmark ( ✅ ) indicates that rule is covered by AutoRest linter tool.
-
Swagger Model Validator - Model Validator validates models defined for body parameters and responses, and matches them against the expected input and output of an operation. To make this real, test examples are required to be specified in a Swagger for every operation defined in a Swagger. Test examples are integrated into a Swagger using the "x-ms-examples" extension, which will be used to test against the defined models. Sample test examples for this extension can be found in the Redis Cache Swagger.
The Azure Developer Experience team will continue to deliver rich tools to validate this checklist.