All supported rules are listed below. To change your settings for any given rule, just add or modify a corresponding item in the rules section of the .openapi-cli.yaml in your working directory.
OpenAPI servers must be present and be a non-empty array.
Schemas and parameters names should be in camelCase. This rule does a lot of string comparison and matching operations, so it may increase time of validation significantly.
Each path parameter in the parameters section must be present in the path string.
License, if provided within the info section, must provide the url field.
Unused schemas defined in components may indicate a mistake. This rule checks for that scenario.
When designing an API it's usually expected to do something successfully, although it might fail. So, this rule validates, that there is at least one response in the operation with a 2xx status code.
This rule enforces that a description field is included in operations definitions.
Enforce presence of the operationId field in each operation. This is a highly recommended practice.
The operationIds are expected to be unique to really identify operations. This rule checks this principle.
The tags field must be present and be a non-empty array in each operation.
The "parameter" object should contain "description" field.
Define path parameters within the operation path definition. Each declaration of the parameter name within path must be a non-empty string. For example, /api/user/{userId}/profie is a valid definition with the userId parameter, but /api/user/{}/profile is not.
Endpoints are less confusing without trailing slashes in the path. Also, tooling may treat example.com/api/users and example.com/api/users/ in the same way, so we suggest you be consistent in your API definition.
Info object must contain the contact field.
APIs are not perfect, and the contact field lets users know who can help.
The "server" object should not point to "example.com" domain.
The server URL must not have a trailing slash.
Tooling may treat example.com and example.com/ in the same way. In the worst case, the latter option when joined with the operations paths might result in example.com//api/users.
The "model" object should contain "description" field.
Parameters in operation objects must be unique definition wide.
Items in tags object of operations should be sorted alphabetically.
This rule enforces the structural validation of the OpenAPI definitions according to the OpenAPI Specification 3.0.2. It can be fine-tuned to disable or change the message level for each specific type of OpenAPI Objects (we call those sub-rules). For example, if you have a custom structure of the servers object, you prevent related error messages by updating your .openapi-cli.yaml to the following pattern:
codeframes: off
rules:
...other rules
oas3-schema:
servers:
level: warning Or even totally disabled:
codeframes: off
rules:
...other rules
oas3-schema:
servers: offBelow, you can find the table of available sub-rules you can update:
| Sub-rule name | OpenAPI Object it corresponds to |
|---|---|
| root | OpenAPI Object |
| info | Open API Info Object |
| contact | Open API Contact Object |
| discriminator | Open API Discriminator Object |
| encoding | Open API Encoding Object |
| example | OpenAPI Example Object |
| external-docs | OpenAPI External Documentation Object |
| header | OpenAPI Header Object |
| license | OpenAPI License Object |
| link | OpenAPI Link Object |
| media-object | OpenAPI Media Type Object |
| operation | OpenAPI Operation Object |
| parameter | OpenAPI Parameter Object |
| path | OpenAPI Path Object |
| request-body | OpenAPI Request Body Object |
| response | OpenAPI Response Object |
| schema | OpenAPI Schema Object |
| secuirty-schema | OpenAPI Security Scheme Object |
| auth-code-flow | Open API Flow Object |
| client-creds-flow | Open API Flow Object |
| implicit-flow | Open API Flow Object |
| password-flow | Open API Flow Object |
| server | OpenAPI Server Object |
| server-variable | OpenAPI Server Variable Object |
| tag | OpenAPI Tag Object |
| xml | OpenAPI XML Obejct |
By default, custom fields, not defined within OpenAPI specification can be included only using x- prefix. This rule enforces such policy.
It is not uncommon to have a bad $ref in your definition. For example, instead of #components/schemas/User one might type #components/schemas/Use.
With this rule enabled, @redocly/openapi-cli will try to find the closest possible valid $ref address in the definition.