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)
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.
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.
The [default][AutoRest tags] API version tag (as seen in the `Basic information` section in the [AutoRest configuration file][AutoRest config] (the README file)) should contain all API paths.
The API path \`${0}\` is not present in any OpenAPI `.json` files enumerated in the list of paths included in the default tag, as seen in the [relevant `Tag:` section][AutoRest tags] in the AutoRest configuration file (the README file).
To fix this error include an OpenAPI `.json` file path in the list of the default API version tag paths (in the [relevant `Tag:` section][AutoRest tags]) that includes the missing API path.
**IMPORTANT**: The error may point to a previous API version. **This does not mean this is a false positive**! It means that the previous API version has an API path that is missing from the default API version.
- Often the API path is missing from the default API version due to casing mismatch; e.g. the path in the new API version has `resourceGroups` in it while the previous one has `resourcegroups`. See examples below.
- If Avocado reports missing a path that you have **intentionally deprecated** or **intentionally removed** but the API version is publicly released (GA, generaly available, not in preview) first you need to get
Breaking Change Board approval. Follow the breaking change process from step 1 in [this diagram](https://aka.ms/pr-diagram). If you already got such approval in a previous PR, follow the [suppression guide]. Mention the scenario you identified.
**Known scenarios where Avocado reports false positive**: Avocado may incorrectly report failures in following two scenarios:
- Your API is deprecated/obsolete [#6627](https://github.com/Azure/azure-sdk-tools/issues/6627) (example case in [PR 24771](https://github.com/Azure/azure-rest-api-specs/pull/24771#issuecomment-1660776189))
- Your API is using the service group folder [#6201](https://github.com/Azure/azure-sdk-tools/issues/6201)
The [default][AutoRest tags] API version tag (as seen in the `Basic information` section in the [AutoRest configuration file][AutoRest config] (the README file)) does not contain the latest API version of given OpenAPI `.json` file.
To fix this error, please make sure the `.json` file at the latest API version path is included in the list of paths for the default tag, in the [relevant `Tag:` section][AutoRest tags] in the AutoRest configuration file (the README file).
Alternatively, change the default API version tag to a valid one by editing the `Basic information` section.
For an example detailed analysis of an occurrence of such error, see [this GitHub comment](https://github.com/Azure/azure-rest-api-specs/pull/23941#issuecomment-1585085436).
The expectation is there is only one default tag, which leads to one SDK package. To release separate SDK packages upon different service resources of the same RP, may consider adopting [Folder Structure for Service Group](https://github.com/Azure/azure-rest-api-specs/blob/main/README.md#folder-structure-for-service-group), which supports a readme configuration file under each sub folder.
