OpenAPI 3 CLI toolbox with rich validation and bundling features.

Currently, @redocly/openapi-cli supports these features:

• Multifile validation. No need to bundle your file before validation.
• Configurable message levels for each rule. You can tailor your experience with @redocly/openapi-cli as you wish.
• Lightning-fast validation. Check 1 Mb file in less than one second.
• Human-readable error messages. Now with stacktrace and codeframes.
• Intuitive suggestions for misspelled types or references.
• Easy to implement custom rules. Need something? Ask us or do it yourself.
• Bundle a multifile definition into a single file.

Unlike other OpenAPI validators, @redocly/openapi-cli defines the possible type tree of a valid OpenAPI definition and then traverses it. This approach is very similar to how compilers work and results in major performance benefits over other approaches. Extend functionality by following the visitor pattern. Both the rules and the bundler features are following the visitor pattern to implement functionality on top of the parsed object.

Run the @redocly/openapi-cli either with npx or after installing it locally.

If using npx, enter the following:

npx @redocly/openapi-cli <command> [options]

Otherwise, install the @redocly/openapi-cli with:

npm install -g @redocly/openapi-cli

or:

yarn global add @redocly/openapi-cli

Run openapi -h to confirm the installation was successful (you'll see the usage information).

Currently, @redocly/openapi-cli provides two commands validate and bundle.

You can bundle your OpenAPI 3 definition into a single file (this may be important for certain tools that lack multifile support). To bundle your OpenAPI 3 definition run following command:

openapi bundle --output <outputName> <startingPoint>

<startingPoint> is the name of your root document and <outputName> is desired output filename.

Supported extensions for outputName are .json, .yml and .yaml.

Beware, if the file specified as the bundler's output already exists, it will be overwritten.

openapi validate [options] <filePath>

Given this command, it will load the given ruleset and traverse the definition via the filePath parameter.

Also, it accepts [options] which can be:

• --short Reduce output to minimum.
• --no-frame Print no codeframes with errors.
• --config <path> Specify custom yaml or json config.

In the section below, you can learn how to provide settings for the @redocly/openapi-cli.

You may supply a configuration file, in YAML format, to control various options.

You can modify (or create) the .openapi-cli.yaml file in the directory from which you are going to run the validator. Also, you can provide the path to the configuration file name other than .openapi-cli.yaml by using --config option when running the @redocly/openapi-cli.

From a high-level, there are two configurable features: codeframes and rules.

codeframes: on
rules:
  ...

Codeframes are enabled by default. You may disable them by setting the value to off.

codeframes: off
rules:
  ...

Rules control validations used on the API definition. You may customize them (and even extend them), or you may utilize the default configuration.

Below is the default config:

codeframes: on
rules:
  oas3-schema: on
  path-param-exists: on
  operation-2xx-response: on
  unique-parameter-names: on
  no-unused-schemas: on
  operation-operationId-unique: on
  path-declarations-must-exist: on

  camel-case-names: off
  api-servers: off
  license-url: off
  no-extra-fields: off
  operation-description: off
  operation-operationId: off
  operation-tags: off
  provide-contact: off
  servers-no-trailing-slash: off

  bundler: off
  debug-info: off

All of the rules are configurable in terms of disabling or changing their severity, or even defining pinpoint exclusions.

Here is an example of a modified use .openapi-cli.yaml file:

codeframes: on
rules:
  no-extra-fields: off
  external-docs:
    url: off
  license-required: warning
  unique-parameter-names: off
  no-unused-schemas:
    level: warning
    excludedPaths:
      - 'openapi.yaml#/components/schemas/Unused'

Each rule can be turned on or off. In addition, you can control the log-level severity, between info, warning, and error. You may also define specific exclusions to the rule, and you can do that by combination of file and bath to the object to be excluded.

Enabling a rule:

rules:
  <rule-name>: on

Disabling a rule:

rules:
  <rule-name>: off

Changing the severity of a rule:

rules:
  <rule-name>:
    level: warning

or

rules:
  <rule-name>: <value>

Possible values are:

• info
• warning
• error

Excluding a specific path:

rules:
  <rule-name>:
    excludedPaths:
      - '<path to file>#</path/to/object>'

The excludedPaths key can accept an array of exclusions. The format includes the path to the file, a # mark, and the path to the object within the file. For example:

rules:
  <rule-name>:
    excludedPaths:
      - 'openapi.yaml#/components/schemas/Pet'

Some rules may have sub-rules. The same configurations still apply:

rules:
  <rule-name>:
    <sub-rule-name>:
      level: info
      excludedPaths:
        - 'openapi.yaml#/components/schemas/Pet'

Read the docs for the built-in rules.

Custom visitors

Transformers

Thanks to graphql-js and eslint for inspiration of the definition traversal approach and to Swagger, Spectral, and Speccy for inspiring the ruleset.