There are some tools that can help you make sure your specifications conform to the accepted guidelines. Better upfront validation before the final pull request is sent will result in quicker turnaround time.
The OpenAPI Hub is a great online website to find your workflow and get access to online validation tools.
Available tools:
VS code extension is our recommendation for authoring swaggers. In addition to having a trivial GUI, it also provides the same functionalities as the Linter tool explained below.
Installation instructions available here.
An alternative to this is the OpenAPI Initiative Swagger editor. This will help find basic issues in a Swagger file. However, we apply a higher bar than this validator, if this site doesn't show errors doesn't mean that your specification is ready to merge.
The various tools mentioned above are also available for local download.
- Install Node.js (7.10.0 or greater)
Linter Validator:
- `npm install -g autorest`
- `autoRest <path to readme.md> --azure-validator=true`
Static Validator (Semantic):
- `npm install -g oav`
- `bash-3.2$ oav validate-spec <spec-path>`
Static Validator (Model):
- `npm install -g oav`
- `bash-3.2$ oav validate-example <spec-path>`
Swagger diff tool
- `npm install -g oad@0.1.7`
- `bash-3.2$ oad compare <old-spec> <new-spec>`
If you believe that the errors reported are false positives or don't apply for your specs, you might consider reviewing the validation errors suppression process and request suppression of these errors.