Another Validator of OpenAPI spec repository Configuration And Directories.
NPM: https://www.npmjs.com/package/@azure/avocado
Avocado validates folder structure and configuration.
Avocado can be integrated into Azure pipeline to validate OpenAPI spec repository. For example, Avocado is used by Azure/azure-rest-api-specs now that will trigger automatically by azure DevOps pipeline when a new pull request is created.
Avocado major functions are listed below:
- For a given directory validate whether exists
specificationand filterreadme.mdunder thespecificationfolder. - Validate whether
readme.mdis autorest specific file which must containsee https://aka.ms/autorest - Validate whether
swagger fileis valid json file, and check all referencedjsonfile (referenced jsonfile marked in json object has the key name"$ref"). - Validate whether the folder has any files without being referenced.
swagger filemust be referenced byreadme.mdor otherswagger file. - Validate whether
swagger filehas a circular reference and report a warning. For more detail, see CIRCULAR REFERENCE - Validate whether each RP folder contains readme file for SDK generation.
npm install -g @azure/avocado
avocado
When type avocado in command line, avocado will validate in the current directory.
NOTE: When running in azure devops Avocado only report new errors involved in PR, but ignore the previous existing errors. When running in local machine, Avocado report all errors.
- Run all specs: Clone the repo
azure/azure-rest-api-specsand run "avocado" in folderazure/azure-rest-api-specs. - Run single service specs: create a folder
specification. and move your service specs folder inspecification. run "avocado"
Level: ERROR
To solve json parse error, you need make sure the json format is valid.
Level: ERROR
Readme file references a non-existing json file. To solve the error you need to check whether the json file is existing.
Level: ERROR
Json file must be referenced by the readme input file section or other json files. Eg, example swagger file should be referenced by main swagger json and for SDK generation main swagger should be referenced by the readme input file section. To solve the error you need to place the non-referenced file to proper place.
Level: ERROR
Each resource provider folder must have a readme file which is required by downstream SDK generation. To solve the error, you need create a readme file contains SDK generation config.
Level: ERROR
Each readme in resource provider folder should follow autorest markdown format. To solve the error, you need check the readme block quote whether contains see https://aka.ms/autorest literally.
Level: ERROR
Swagger json file api version must consistent with its file path. Swagger can define swagger 2.0 basic-structure which contains api version. To solve the error, you need modify either your swagger file location or swagger file api version to make both of them consistent.
Level: WARNING
To solve circular reference, you should break the circular chain.
Example: a.json -> b.json->c.json
// a.json
{ "$ref": "b.json" }// b.json
{ "$ref": "c.json" }// c.json
{ "$ref": "a.json" }graph TD
A((a.json))-->B((b.json))
B-->C((c.json))
C-->A
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.