mirror of
https://github.com/LukeHagar/redocly-cli.git
synced 2025-12-06 04:21:09 +00:00
130 lines
7.4 KiB
Markdown
130 lines
7.4 KiB
Markdown
---
|
|
slug: /docs/cli/rules/built-in-rules
|
|
---
|
|
|
|
# Built-in rules
|
|
|
|
The built-in rules are the ones we use ourselves and think apply to the majority of APIs. Some have some additional [configuration](#rule-configuration-syntax), but otherwise all you need to do is decide whether each rule should `error`, `warn` or be `off`.
|
|
|
|
All the built-in rules are listed here, roughly grouped by the OpenAPI object they apply to.
|
|
The _Special rules_ group contains rules that may apply to multiple objects or to the entire OpenAPI document.
|
|
|
|
{% admonition type="info" %}
|
|
Build [configurable rules](./configurable-rules.md) if the rule you need isn't listed.
|
|
{% /admonition %}
|
|
|
|
### Special rules
|
|
|
|
- [no-unresolved-refs](./no-unresolved-refs.md): Every `$ref` must exist
|
|
- [no-unused-components](./no-unused-components.md): All components must be used
|
|
- [security-defined](./security-defined.md): Security rules must be defined, either globally or per-operation
|
|
- [spec](./spec.md): Conform to the declared OpenAPI specification version
|
|
- [spec-components-invalid-map-name](./spec-components-invalid-map-name.md): Use only alphanumeric and basic punctuation as key names in the components section
|
|
- [spec-strict-refs](./spec-strict-refs.md) Restricts the usage of the `$ref` keyword.
|
|
|
|
### Info
|
|
|
|
- [info-contact](./info-contact.md): Contact section is defined under `info`
|
|
- [info-license](./info-license.md): License section is defined under `info`
|
|
- [info-license-url](./info-license-url.md): License section contains a `url` to the license
|
|
|
|
### Operations
|
|
|
|
- [operation-2xx-response](./operation-2xx-response.md): Every operation needs at least one 2xx response
|
|
- [operation-4xx-response](./operation-4xx-response.md): Every operation needs at least one 4xx response
|
|
- [operation-4xx-problem-details-rfc7807](./operation-4xx-problem-details-rfc7807.md): All 4xx responses use RFC7807 format
|
|
- [operation-description](./operation-description.md): Description field is required for every operation
|
|
- [operation-operationId](./operation-operationId.md): OperationId is required for every operation
|
|
- [operation-operationId-unique](./operation-operationId-unique.md): OperationId must be unique
|
|
- [operation-operationId-url-safe](./operation-operationId-url-safe.md): OperationIds can only contain characters that are safe to use in URLs
|
|
- [operation-summary](./operation-summary.md): Summary is required for every operation
|
|
|
|
### Parameters
|
|
|
|
- [boolean-parameter-prefixes](./boolean-parameter-prefixes.md): All boolean paramater names start with a particular prefix (such as "is")
|
|
- [no-invalid-parameter-examples](./no-invalid-parameter-examples.md): Parameter examples must match declared schema types
|
|
- [operation-parameters-unique](./operation-parameters-unique.md): No repeated parameter names within an operation
|
|
- [parameter-description](./parameter-description.md): Parameters must all have descriptions
|
|
- [path-declaration-must-exist](./path-declaration-must-exist.md): Paths must define template variables where placeholders are needed
|
|
- [path-not-include-query](./path-not-include-query.md): No query parameters in path declarations (declare them as parameters with `in: query`)
|
|
- [path-parameters-defined](./path-parameters-defined.md): Path template variables must be defined as parameters
|
|
|
|
### Paths
|
|
|
|
- [no-ambiguous-paths](./no-ambiguous-paths.md): No path can match more than one PathItem entry, including template variables
|
|
- [no-http-verbs-in-paths](./no-http-verbs-in-paths.md): Verbs like "get" cannot be used in paths
|
|
- [no-identical-paths](./no-identical-paths.md): Paths cannot be identical, including template variables
|
|
- [no-path-trailing-slash](./no-path-trailing-slash.md): No trailing slashes on paths
|
|
- [path-excludes-patterns](./path-excludes-patterns.md): Set a regular expression that cannot be used in paths
|
|
- [path-segment-plural](./path-segment-plural.md): All URL segments in a path must be plural (exceptions can be configured)
|
|
- [paths-kebab-case](./paths-kebab-case.md): Paths must be in `kebab-case` format
|
|
|
|
### Requests, Responses, and Schemas
|
|
|
|
- [no-enum-type-mismatch](./no-enum-type-mismatch.md): Enum options must match the data type declared in the schema
|
|
- [no-example-value-and-externalValue](./no-example-value-and-externalValue.md): Either the `value` or `externalValue` may be present, but not both
|
|
- [no-invalid-media-type-examples](./no-invalid-media-type-examples.md): Example request bodies must match the declared schema
|
|
- [no-invalid-schema-examples](./no-invalid-schema-examples.md): Schema examples must match declared types
|
|
- [request-mime-type](./request-mime-type.md): Configure allowed mime types for requests
|
|
- [response-mime-type](./response-mime-type.md): Configure allowed mime types for responses
|
|
- [response-contains-header](./response-contains-header.md): List headers that must be included with specific response types
|
|
- [response-contains-property](./response-contains-property.md): Specify properties that should be present in specific response types
|
|
- [scalar-property-missing-example](./scalar-property-missing-example.md): All required scalar (non-object) properties must have examples defined
|
|
- [required-string-property-missing-min-length](./required-string-property-missing-min-length.md): All required properties of type string must have a `minLength` configured
|
|
|
|
### Servers
|
|
|
|
- [no-empty-servers](./no-empty-servers.md): Servers array must be defined
|
|
- [no-server-example.com](./no-server-example-com.md): `example.com` is not acceptable as a server URL
|
|
- [no-server-trailing-slash](./no-server-trailing-slash.md): Server URLs cannot end with a slash (paths usually start with a slash)
|
|
- [no-server-variables-empty-enum](./no-server-variables-empty-enum.md): Require that enum values are set if variables are used in server definition
|
|
- [no-undefined-server-variable](./no-undefined-server-variable.md): All variables in server definition must be defined
|
|
|
|
### Tags
|
|
|
|
- [operation-singular-tag](./operation-singular-tag.md): Each operation may only have one tag
|
|
- [operation-tag-defined](./operation-tag-defined.md): Tags can only be used if they are defined at the top level
|
|
- [tag-description](./tag-description.md): Tags must have descriptions
|
|
- [tags-alphabetical](./tags-alphabetical.md): Tags in the top-level `tags` section must appear alphabetically
|
|
|
|
## Rule configuration syntax
|
|
|
|
To change your settings for any given rule, add or modify its corresponding entry in your Redocly configuration file.
|
|
|
|
You can specify global settings in the top-level `rules` object, or use per-API settings by adding a `rules` object under each API in `apis`.
|
|
|
|
You can format each entry in the `rules` object in one of the following ways:
|
|
|
|
- Short syntax with single-line configuration `rule-name: {severity}`, where `{severity}` is one of `error`, `warn` or `off`. You can't configure additional rule options with this syntax.
|
|
|
|
```yaml
|
|
apis:
|
|
main:
|
|
root: ./openapi/openapi.yaml
|
|
rules:
|
|
specific-api-rule: warn
|
|
rules:
|
|
example-rule-name: error
|
|
```
|
|
|
|
- Verbose syntax, where you can configure additional options for rules that support them.
|
|
|
|
```yaml
|
|
apis:
|
|
main:
|
|
root: ./openapi/openapi.yaml
|
|
rules:
|
|
specific-api-rule:
|
|
severity: warn
|
|
rules:
|
|
example-rule-name:
|
|
severity: error
|
|
rule-option-one: value
|
|
rule-option-two: value
|
|
```
|
|
|
|
## Next steps
|
|
|
|
- Learn more about [API linting](../api-standards.md), or follow the [guide to configuring a ruleset](../guides/configure-rules.md).
|
|
- If you didn't find the rule you need, build a [configurable rule](./configurable-rules.md) for a perfect linting fit.
|