redocly/cli repository overview

⁠Redocly CLI

​ Open source command-line utility from @Redocly⁠ with OpenAPI superpowers. Build, manage and quality-check OpenAPI descriptions, configure and execute API governance, and publish beautiful API documentation. Supports OpenAPI 3.1, 3.0 and OpenAPI 2.0 (legacy Swagger format). ​

• API governance Check that your API is up to standard on every revision. Our ready-made rulesets, built-in and configurable rules let you compose the API standards that fit each of your APIs.
• Great API docs Use open source Redoc or our hosted tools to create clear and useful documentation with local previews and static builds available.
• Manage OpenAPI files Split an OpenAPI description into logical chunks, bundle the chunks to create a single file, or even join existing definitions into one.
• Transform OpenAPI Publish a subset of endpoints, or use decorators to enhance your existing OpenAPI by adding, changing, or removing content. ​

⁠Installation

​ Grab the image: ​

docker pull redocly/cli

​ Redocly CLI needs file access, so mount the directory with your configuration and OpenAPI files when you use this command. For example, to lint a file in the current working directory, use this command: ​

docker run --rm -v $PWD:/spec redocly/cli lint openapi.yaml

​

⁠Usage

​ Read the detailed docs⁠, and replace the redocly command with docker run redocly/cli. Remember to mount the directories you want docker to be able to access when running the commmand. ​ Get command help: ​

docker run redocly/cli --help

​

⁠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: ​

docker run --rm -v $PWD:/spec 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. ​

⁠Lint an API description against a standard

​ Check your API meets the expected standards using lint to ensure quality in every version of your API. Our API linter is designed for speed on even large documents, so 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: ​

docker run --rm -v $PWD:/spec redocly/cli lint openapi.yaml

​ Configure the rules as you wish. No JSONPath here, just type-aware expressions that understand the OpenAPI structure. You can either use the built-in rules⁠ to mix-and-match your ideal API standard, 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, we've got those too. ​ Multiple files supported so you don't need to bundle your API description to lint it, just give the entry point and Redocly CLI does the rest. ​ Learn more about API standards and configuring Redocly rules⁠. ​

⁠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. ​

⁠Community

​ Redocly CLI is an open source project. Find us at Redocly/redocly-cli on GitHub⁠ and join the community. ​