Last updated 1 week ago

Redocly OpenAPI CLI

Redocly OpenAPI CLI is an open source command-line tool used to:

  • Lint and bundle your OpenAPI definition(s).
  • Decorate your APIs (add or remove data).
  • Preview reference docs for local development.
  • Split single-file OpenAPI files into a multi-file format.
  • Integrate with Redocly's API registry (coming soon).
  • Build production-ready reference docs (requires an Enterprise license key).

Redocly OpenAPI CLI does not:

  • Integrate to Redocly's API Registry - instead, integrate by connecting to your source control, uploading a file, or directly linking to a URL.
  • Structure your OpenAPI repository - instead, use our Create OpenAPI repo tool.

Redocly OpenAPI CLI can be:

Features

Currently, Redocly OpenAPI CLI supports these features:

  • Multi-file validation. No need to bundle your files before validation.
  • Support for remote $refs.
  • Configurable severity levels for each rule. Tailor your experience with Redocly OpenAPI CLI to suit your needs.
  • Lightning-fast validation. Check a 1 MB file in less than one second.
  • Human-readable error messages. Now with stacktraces and codeframes.
  • Intuitive suggestions for misspelled types or references.
  • Easy-to-implement custom rules. Need something? Ask us or do it yourself.
  • Bundle a multi-file definition into a single file for compatibility with external tools.
  • Preview reference docs.
  • Support for OAS 3.0 and Swagger 2 (OAS 3.1 is coming soon).

What makes Redocly OpenAPI CLI different

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.

Redocly OpenAPI CLI comes with a set of built-in rules, but you can extend its functionality by creating your own rules. Both the lint and the bundle features follow the visitor pattern for adding custom behavior on the parsed object.

Lint

Preprocessors
Rules

Bundle

Preprocessors
Rules
Decorators

Installation and usage

Install @redocly/openapi-cli locally or run it with npx.

npx

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

npm

npm install -g @redocly/openapi-cli

yarn

yarn global add @redocly/openapi-cli

After installing it locally, run openapi -h to confirm the installation was successful. The output shows the list of supported commands and brief instructions for using them. General usage syntax is the following:

openapi <command> [options]

Read more about supported commands in Redocly OpenAPI CLI.

The source code is available in the OpenAPI-CLI GitHub repository.