@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

@Redocly CLI is your all-in-one OpenAPI utility. It builds, manages, improves, and quality-checks your OpenAPI descriptions, all of which comes in handy for various phases of the API Lifecycle. Create your own rulesets to make API governance easy, and publish beautiful API reference documentation. Supports OpenAPI 3.1, 3.0 and OpenAPI 2.0 (legacy Swagger).

Usage

Node

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

Alternatively, install it globally with npm:

npm install @redocly/cli -g

Then you can use it as redocly [command] [options], for example:

redocly lint path-to-root-file.yaml

The minimum required versions of Node.js and NPM are 14.19.0 and 7.0.0 respectively.

Docker

To give the Docker container access to the OpenAPI description files, you need to mount the containing directory as a volume. Assuming the API description is rooted in the current working directory, you need the following command:

docker run --rm -v $PWD:/spec redocly/cli lint path-to-root-file.yaml

To build and run with a local image, run the following from the project root:

docker build -t redocly/cli .
docker run --rm -v $PWD:/spec redocly/cli lint path-to-root-file.yaml

Common tasks

Generate API reference documentation

Redocly CLI is a great way to render API reference documentation. It uses open source Redoc to build your documentation. Use a command like this:

redocly build-docs openapi.yaml

Your API reference docs are in redoc-static.html by default. You can customize this in many ways. Read the main docs for more information.

:bulb: Redocly also has hosted API reference docs, a (commercial) alternative to Redoc. Both Redoc and Redocly API reference docs can be worked on locally using the preview-docs command.

Bundle multiple OpenAPI documents

Having one massive OpenAPI description can be annoying, so most people split them up into multiple documents via $ref, only to later find out some tools don't support $ref or don't support multiple documents. Redocly CLI to the rescue! It has a bundle command you can use to recombine all of those documents back into one single document. The bundled output that Redocly CLI provides is clean, tidy, and looks like a human made it.

Automate API guidelines with Linting

Check that your API matches the expected API guidelines by using the lint command. API guidelines are an important piece of API governance. They help to keep APIs consistent by enforcing the same standards and naming conventions, and they can also guide API teams through potential security hazards and other pitfalls. Automating API guidelines means you can keep APIs consistent and secure throughout their lifecycle. Even better, you can shape the design of the API before it even exists by combining API linting with a design-first API workflow.

Our API linter is designed for speed on even large documents, and it's easy to run locally, in CI, or anywhere you need it. It's also designed for humans, with meaningful error messages to help you get your API right every time.

Try it like this:

redocly lint openapi.yaml

Configure the rules as you wish. Other API Linters use complicated identifiers like JSONPath, but Redocly makes life easy with simple expressions that understand the OpenAPI structure. You can either use the built-in rules to mix-and-match your ideal API guidelines, or break out the tools to build your own.

Format the output in whatever way you need. The stylish output is as good as it sounds, but if you need JSON or Checkstyle outputs to integrate with other tools, the lint command can output those too.

Multiple files supported so you don't need to bundle your API description to lint it; just point Redocly CLI at the "entry point" (e.g.: openapi.yaml) and it handles the rest.

Learn more about API standards and configuring Redocly rules.

Transform an OpenAPI description

If your OpenAPI description isn't everything you hoped it would be, enhance it with the Redocly decorators feature. This allows you to:

• Publish reference docs with a subset of endpoints for public use
• Improve the docs by adding examples and descriptions
• Adapt an existing OpenAPI description, and replace details like URLs for use on staging platforms

Data collection

This tool collects data to help Redocly improve our products and services. You can opt out by setting the REDOCLY_TELEMETRY environment variable to off.

More resources

Read the detailed docs.

Credits

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

Development

Contributions are welcome! All the information you need is in CONTRIBUTING.md.