For a large number of rules, we can automatically detect issues in a spec file. In the review process, we first start by using the VS Code extension to flag these problems. You can fix these ahead of time by using the VS Code extension when writing your spec.
Get the VS Code extension here: https://github.com/Azure/openapi-lint-extension. It helps you see each validation rule in situ, as well as providing other useful quality-of-life features for writing OpenAPI specs.
These pages describe each rule in detail and how to fix the issue. They also show the effect that each issue has on the generated code, to make it easier to understand the rational behind the rule.
Note there currently an exception to many of these rules for existing specs, since they were written before guidance for these rules. If you are updating an existing spec with a small change (e.g. adding a feature), make sure to mention this in your PR. We will work with your team to get your existing spec to follow all of these rules in the future, as this exception is temporary.
- AnonymousParameterTypes
- AvoidNestedProperties
- DefaultInEnum
- DescriptiveDescriptionRequired
- ModelTypeIncomplete
- NonEmptyClientName
- OperationDescriptionRequired
- OperationIdNounInVerb
- OperationIdSingleUnderscore
- ParameterDescriptionRequired
- RequiredPropertiesMustExist
- ResponseRequired
- ValidFormats
- XmsPathsInPath