# @zhenglaizhang/avocado > A validator of OpenAPI configurations Latest version **0.7.2** (published 2020-06-18) · MIT license · 0 weekly downloads ## Install ```sh npm install @zhenglaizhang/avocado pnpm add @zhenglaizhang/avocado yarn add @zhenglaizhang/avocado bun add @zhenglaizhang/avocado ``` Provides the command `avocado`. ## Health **Score 40/100 (D)** — status: abandoned. Positive: has types; no vulnerabilities; high maintenance score; high quality score. Warnings: low downloads; no esm support; pre 1.0. Negative: abandoned. ## Facts | | | |---|---| | Version | 0.7.2 | | Published | 2020-06-18 | | First published | 2020-06-08 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | bundled | | Module format | CommonJS | | Dependencies | 13 | | Unpacked size | 94.8 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 23 | | Author | Microsoft | | Maintainers | zhenglaizhang | | Keywords | openapi, validator | ## Links - npm: https://www.npmjs.com/package/@zhenglaizhang/avocado - Repository: https://github.com/Azure/avocado - Homepage: https://github.com/Azure/avocado#readme - Issues: https://github.com/Azure/avocado/issues - npm.io page: https://npm.io/package/@zhenglaizhang/avocado ## Dependencies (13) - [yargs](https://npm.io/package/yargs.md) ^15.3.1 - [js-yaml](https://npm.io/package/js-yaml.md) ^3.13.1 - [commonmark](https://npm.io/package/commonmark.md) ^0.29.0 - [@ts-common/fs](https://npm.io/package/@ts-common/fs.md) ^0.2.0 - [@ts-common/json](https://npm.io/package/@ts-common/json.md) ^0.3.1 - [node-object-hash](https://npm.io/package/node-object-hash.md) ^1.4.2 - [@ts-common/iterator](https://npm.io/package/@ts-common/iterator.md) ^0.3.6 - [@ts-common/string-map](https://npm.io/package/@ts-common/string-map.md) ^0.3.0 - [@ts-common/json-parser](https://npm.io/package/@ts-common/json-parser.md) ^0.8.0 - [@azure/openapi-markdown](https://npm.io/package/@azure/openapi-markdown.md) ^0.9.1 - [@ts-common/async-iterator](https://npm.io/package/@ts-common/async-iterator.md) ^0.2.2 - [@azure/swagger-validation-common](https://npm.io/package/@azure/swagger-validation-common.md) ^0.0.5 - [@ts-common/commonmark-to-markdown](https://npm.io/package/@ts-common/commonmark-to-markdown.md) ^1.2.0 ## Alternatives - [@sindresorhus/slugify](https://npm.io/package/@sindresorhus/slugify.md) — 3.7M weekly downloads - [solid-js](https://npm.io/package/solid-js.md) — 2.7M weekly downloads - [expo-glass-effect](https://npm.io/package/expo-glass-effect.md) — 2.5M weekly downloads - [nanoassert](https://npm.io/package/nanoassert.md) — 780.8K weekly downloads - [@ffmpeg/ffmpeg](https://npm.io/package/@ffmpeg/ffmpeg.md) — 529.5K weekly downloads ## Recent versions - 0.7.2 (latest) — 2020-06-18 - 0.7.1 — 2020-06-16 - 0.7.0 — 2020-06-08 ## README # Avocado Another Validator of OpenAPI spec repository Configuration And Directories. [![Build Status](https://dev.azure.com/azure-sdk/public/_apis/build/status/public.avocado?branchName=master)](https://dev.azure.com/azure-sdk/public/_build/latest?definitionId=120&branchName=master) NPM: https://www.npmjs.com/package/@azure/avocado ## Overview 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 `specification` and filter `readme.md` under the `specification` folder. - Validate whether `readme.md` is autorest specific file which must contain `see https://aka.ms/autorest` - Validate whether `swagger file` is valid json file, and check all referenced `json` file (`referenced json` file marked in json object has the key name `"$ref"`). - Validate whether the folder has any files without being referenced. `swagger file` must be referenced by `readme.md` or other `swagger file`. - Validate whether `swagger file` has a circular reference and report a warning. For more detail, see [CIRCULAR REFERENCE](#circular-reference) - Validate whether each RP folder contains readme file for SDK generation. ## How to use ### Install `npm install -g @azure/avocado` ### Usage `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. ### Example - Run all specs: Clone the repo `azure/azure-rest-api-specs` and run "avocado" in folder `azure/azure-rest-api-specs`. - Run single service specs: create a folder `specification`. and move your service specs folder in `specification`. run "avocado" ## How to solve errors ### JSON_PARSE Level: ERROR To solve json parse error, you need make sure the json format is valid. ### NO_JSON_FILE_FOUND Level: ERROR Readme file references a non-existing json file. To solve the error you need to check whether the json file is existing. ### UNREFERENCED_JSON_FILE 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. ### MISSING_README 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. ### NOT_AUTOREST_MARKDOWN 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. ### INCONSISTENT_API_VERSION Level: ERROR Swagger json file api version must consistent with its file path. Swagger can define [swagger 2.0 basic-structure](https://swagger.io/docs/specification/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. ### CIRCULAR_REFERENCE Level: WARNING To solve circular reference, you should break the circular chain. Example: `a.json` -> `b.json`->`c.json` ```json // a.json { "$ref": "b.json" } ``` ```json // b.json { "$ref": "c.json" } ``` ```json // c.json { "$ref": "a.json" } ``` ```mermaid graph TD A((a.json))-->B((b.json)) B-->C((c.json)) C-->A ``` ## Contributing 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](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. --- _Source: https://npm.io/package/@zhenglaizhang/avocado · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._