@redocly/cli

What is @redocly/cli?

@redocly/cli is a command-line tool for working with OpenAPI definitions. It provides a suite of tools to lint, bundle, and preview OpenAPI definitions, making it easier to maintain and document APIs.

What are @redocly/cli's main functionalities?

Linting

Linting helps ensure that your OpenAPI definitions adhere to best practices and standards. The command checks the OpenAPI file for errors and warnings.

redocly lint openapi.yaml

Bundling

Bundling combines multiple OpenAPI files into a single file. This is useful for managing large APIs with multiple components. The command takes an input file and outputs a bundled file.

redocly bundle openapi.yaml -o bundled.yaml

Previewing

Previewing allows you to see how your OpenAPI documentation will look. The command starts a local server to preview the documentation in a web browser.

redocly preview-docs openapi.yaml

Other packages similar to @redocly/cli

swagger-cli

swagger-cli is a command-line tool for Swagger and OpenAPI. It provides similar functionalities like bundling and validating OpenAPI definitions. However, it lacks some of the advanced linting and preview features provided by @redocly/cli.

speccy

speccy is a command-line tool for linting, bundling, and transforming OpenAPI specifications. It offers similar linting and bundling capabilities but does not provide a preview feature like @redocly/cli.

README

Redocly CLI toolset

Redocly CLI toolbox with rich validation and bundling features.

Features

Currently, @redocly/cli supports these features:

• Multifile validation. No need to bundle your file before validation.
• Lightning-fast validation. Lint a 1 Mb file in less than one second.
• Built-in rules for common validations.
• Configurable severity levels for each rule.
• Human-readable error messages with codeframes and stylish format options.
• Intuitive suggestions for misspelled types or references.
• Easy to implement custom rules.
• Bundle a multifile definition into a single file.
• Decorators to modify a validated definition during bundling.
• Preview reference docs for local development.
• Support for OpenAPI 2 (fka Swagger) and OpenAPI 3.0.
• Support for OpenAPI 3.1 (coming soon).

What makes this tool different

Unlike other OpenAPI linters, @redocly/cli defines the possible type tree of a valid OpenAPI definition and then traverses it. This approach is very similar to how linters for programming languages work and results in major performance benefits over other approaches. Extend functionality at different points in the lifecycle with preprocessors, rules, and decorators.

TLDR

npx @redocly/cli lint path-to-root-file.yaml

Read the docs

Credits

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