Redocly Tutorial: How to Use the Redocly CLI

Welcome to this comprehensive tutorial on the Redocly CLI! Redocly CLI is a powerful, all-in-one command-line tool for OpenAPI and Swagger definitions. It helps you build, manage, and quality-check your API descriptions throughout the entire API lifecycle. Whether you're a developer, a technical writer, or an API product manager, this tool has something for you.

This tutorial aims to be a deep dive into the Redocly CLI, taking you from a beginner to a confident user. We will cover everything from installation to advanced features like custom linting rules and CI/CD integration. By the end of this tutorial, you will be able to integrate Redocly CLI into your daily workflow to improve your API quality and documentation.

What is Redocly CLI?

As stated in its official documentation, Redocly CLI is your "all-in-one OpenAPI utility." It supports OpenAPI 3.1, 3.0, 2.0 (legacy Swagger), AsyncAPI, and more. It's designed to help you with:

• API Governance: Enforce API design standards and consistency with powerful and configurable linting.
• API Documentation: Generate beautiful and interactive API reference documentation with Redoc.
• Workflow Improvement: Bundle multi-file API definitions, split large definitions into smaller files, and get valuable statistics about your APIs.

This tool is built with performance and user experience in mind, providing fast execution and human-readable error messages.

Why Use Redocly CLI?

In today's API-first world, maintaining high-quality API definitions is crucial. Redocly CLI helps you achieve this by:

• Automating Quality Checks: The linting feature automates the process of checking your API definitions against a set of rules, ensuring consistency and preventing common errors.
• Improving Collaboration: By allowing you to split a large API definition into multiple files, it becomes easier for teams to work on different parts of the API simultaneously. The bundle command then puts everything back together.
• Enhancing Developer Experience: High-quality, interactive documentation generated by build-docs makes it easier for developers to understand and consume your APIs.
• Integrating with your Toolchain: Redocly CLI can be easily integrated into your CI/CD pipeline, making API quality a part of your automated workflow.

What This Tutorial Will Cover

This tutorial is structured to provide a step-by-step guide to mastering Redocly CLI. Here's what we will cover:

• Chapter 1: Getting Started: We'll cover the prerequisites and show you how to install and run Redocly CLI.
• Chapter 2: Core Commands and Features: This chapter will be a deep dive into the most important commands: lint, bundle, split, build-docs, and stats.
• Chapter 3: Advanced Topics: We'll explore the redocly.yaml configuration file and how to integrate Redocly CLI into a GitHub Actions workflow.
• Chapter 4: Practical Example: We will walk through a complete, real-world workflow, from creating a multi-file API definition to generating documentation.

Let's get started!

Chapter 1: Getting Started with Redocly CLI

This chapter will guide you through the first steps of using Redocly CLI, from installation to running your first command.

Prerequisites

Before you start, make sure you have the following installed on your system:

• Node.js and npm: Redocly CLI is a Node.js application. You will need Node.js (version 22.12.0 or higher) and npm (version 10.9.2 or higher) installed. You can check your versions by running node -v and npm -v in your terminal.

Installation

You have several options to install and use Redocly CLI. Choose the one that best fits your needs.

Using npx (Recommended for quick use)

If you just want to try out Redocly CLI without a global installation, you can use npx, the npm package runner. This command will download and run the latest version of Redocly CLI.

npx @redocly/cli@latest --version

To use any redocly command, just prepend npx @redocly/cli@latest. For example:

npx @redocly/cli@latest lint openapi.yaml

This is a great way to use Redocly CLI in CI/CD environments or if you don't want to clutter your system with global packages.

Global Installation with npm

For regular use, a global installation is more convenient. It makes the redocly command directly available in your terminal.

npm install -g @redocly/cli@latest

After installation, you can verify it by checking the version:

redocly --version

Now you can run commands like this:

redocly lint openapi.yaml

Using Docker

If you prefer to use Docker, Redocly provides a pre-built Docker image. This is useful for isolating the tool from your local environment.

First, pull the image from Docker Hub:

docker pull redocly/cli

To run a command, you need to mount your current working directory (where your API files are) as a volume to the Docker container.

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

In this command, $PWD refers to your current directory, which is mounted to the /spec directory inside the container. You then need to refer to your files using the /spec path.

Basic Command Structure

The basic structure for using Redocly CLI is:

redocly [command] [arguments] [options]

• command: The action you want to perform (e.g., lint, bundle).
• arguments: Usually the path to your root API definition file (e.g., openapi.yaml).
• options: Flags to customize the command's behavior (e.g., -output, -format).

You can always get help for a specific command by using the --help option:

redocly lint --help

Now that you have Redocly CLI installed and you understand the basic command structure, let's move on to exploring its powerful features.

Chapter 2: Core Commands and Features

This chapter covers the core commands of Redocly CLI. We'll explore how to lint, manage, document, and analyze your API definitions. For the examples in this chapter, we'll use a simple openapi.yaml file.

Let's create a file named openapi.yaml with the following content:

openapi: 3.0.0
info:
  title: Simple Pet Store API
  version: 1.0.0
  description: A simple API to manage pets.
servers:
  - url: <http://localhost:8080/api>
paths:
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      responses:
        '200':
          description: An array of pets.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        tag:
          type: string

Section 2.1: Linting Your API Descriptions (lint)

API linting is the process of checking your API definition file for consistency, correctness, and style. It helps you enforce API design guidelines and catch potential issues before they reach production.

Basic Usage

The lint command is used to check your API definition against a set of rules.

redocly lint openapi.yaml

By default, redocly lint uses the recommended ruleset. If our openapi.yaml has issues, the output will detail them. For our example file, the output should be:

validating openapi.yaml...
openapi.yaml: validated in 58ms

Woohoo! Your API description is valid. 🎉

Configuring Rules

Redocly CLI comes with three built-in configurable rulesets:

• minimal: A small set of rules that mainly checks for specification validity.
• recommended: A more comprehensive set of rules that enforces common best practices. This is the default.
• recommended-strict: A stricter version of the recommended ruleset.

You can specify a ruleset with the --extends option:

redocly lint openapi.yaml --extends=minimal

You can also create your own custom rulesets in a redocly.yaml configuration file. We will cover this in Chapter 3.

Output Formats

The lint command supports various output formats using the --format option, which is very useful for integrating with other tools.

• codeframe (default): Shows the code context for each problem.
• stylish: A more compact, human-readable format.
• json: Outputs a JSON object with all the problems, perfect for machine processing.
• checkstyle: XML format compatible with Checkstyle.
• github-actions: A format that integrates with GitHub Actions annotations.
• markdown: A Markdown table of the results, great for reports.

Example of using the stylish format:

redocly lint openapi.yaml --format=stylish

Ignoring Problems

Sometimes you may need to ignore a specific problem. You can generate a .redocly.lint-ignore.yaml file to suppress errors and warnings.

redocly lint openapi.yaml --generate-ignore-file

This command will create an ignore file. If you run lint again, the problems listed in this file will be ignored. This gives you granular control over the linting process.

Section 2.2: Managing API Descriptions with bundle and split

As your API grows, managing a single, monolithic OpenAPI file becomes cumbersome. Redocly CLI provides two commands to help with this: split and bundle.

Splitting a Large OpenAPI File (split)

The split command allows you to break down a large API definition file into a more manageable, multi-file structure. It extracts components, paths, and examples into separate files and folders.

Let's split our openapi.yaml:

redocly split openapi.yaml --outDir=split-api

This command will create a split-api directory with the following structure:

split-api/
├── components/
│   └── schemas/
│       └── Pet.yaml
├── paths/
│   └── pets.yaml
└── openapi.yaml

The new openapi.yaml in split-api will now use $ref to link to the external files:

# split-api/openapi.yaml
openapi: 3.0.0
info:
  title: Simple Pet Store API
# ...
paths:
  /pets:
    $ref: ./paths/pets.yaml
components:
  schemas:
    Pet:
      $ref: ./components/schemas/Pet.yaml

This makes it much easier to manage different parts of your API.

Bundling Multiple Files (bundle)

The bundle command does the opposite of split. It takes a root API definition file and resolves all the local $refs to create a single, self-contained file. This is useful for tools that don't support multi-file definitions.

Let's bundle our split API back into a single file:

redocly bundle split-api/openapi.yaml --output bundled-api.yaml

The bundled-api.yaml will have the same content as our original openapi.yaml.

Dereferencing

The bundle command can also create a fully dereferenced file, where all $refs (including remote ones) are resolved and replaced with their content.

redocly bundle split-api/openapi.yaml --output dereferenced-api.yaml --dereferenced

This can be useful, but be aware that it can make the file much larger and that circular references can cause issues with JSON output.

Section 2.3: Generating API Documentation (build-docs)

One of the most powerful features of Redocly CLI is its ability to generate beautiful, interactive API reference documentation using the open-source Redoc engine.

Basic Usage

To generate documentation, use the build-docs command:

redocly build-docs openapi.yaml

This will create a redoc-static.html file in your current directory. Open it in your browser to see your documentation.

You can specify a different output file with the -o or --output option:

redocly build-docs openapi.yaml -o my-api-docs.html

Customizing the Output

You can customize the look and feel of your documentation using the --theme.openapi option. This allows you to change colors, fonts, and even disable parts of the UI like the search bar.

For example, to disable the search bar:

redocly build-docs openapi.yaml --theme.openapi.disableSearch

You can find all the available theme options in the official Redocly documentation.

For even more control, you can provide your own Handlebars template to render the documentation. This is an advanced feature that allows for complete customization of the HTML output.

Section 2.4: Getting API Statistics (stats)

The stats command provides useful metrics about your API definition, such as the number of paths, operations, schemas, and more.

How to Get Statistics

To get statistics for your API, simply run:

redocly stats openapi.yaml

The default output is in the stylish format:

Document: openapi.yaml stats:

🚗 References: 1
📦 External Documents: 0
📈 Schemas: 1
👉 Parameters: 0
🔗 Links: 0
🔀 Path Items: 1
👷 Operations: 1
🔖 Tags: 0

openapi.yaml: stats processed in 22ms

Different Formats

Like the lint command, stats supports different output formats with the --format option. The json and markdown formats are particularly useful.

• -format=json:

redocly stats openapi.yaml --format=json

This is great for feeding the stats into other tools or dashboards.

• -format=markdown:

redocly stats openapi.yaml --format=markdown

This generates a Markdown table, which is perfect for reports or for use in GitHub Actions summaries, as we'll see in the next chapter.

Chapter 3: Advanced Topics

In this chapter, we'll dive into some of the more advanced features of Redocly CLI, including the powerful configuration file and integration with CI/CD pipelines.

Configuration File (redocly.yaml)

While you can use Redocly CLI entirely from the command line, a redocly.yaml configuration file allows you to store your configuration in one place, making your commands shorter and your configuration reusable.

Let's create a redocly.yaml file in the root of our project:

# redocly.yaml

# This is a sample configuration file.
# For a full list of options, see the Redocly documentation.

apis:
  main:
    root: openapi.yaml

lint:
  extends:
    - recommended
  rules:
    # You can customize rules here.
    # For example, make sure all operations have a summary.
    operation-summary: error

Structure of the Configuration File

• apis: This section allows you to define aliases for your API definitions. In the example above, we've created an alias main for our openapi.yaml file.
• lint: This section contains the configuration for the lint command. You can specify which rulesets to extend and customize individual rules.
• Other sections: You can also configure other parts of Redocly, like decorators for transforming your API.

Using API Aliases

With the apis section configured, you can now use the alias main instead of the file path in your commands:

redocly lint main
redocly stats main
redocly build-docs main

This is especially useful when you have multiple APIs in your project. If you run redocly lint without any arguments, it will lint all the APIs defined in the apis section.

Continuous Integration (CI)

Integrating Redocly CLI into your CI/CD pipeline is a fantastic way to automate API quality checks. Here's an example of how to use it with GitHub Actions.

Create a file named .github/workflows/redocly.yaml:

name: Redocly CLI Checks

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  lint-and-stats:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '16'

      - name: Install Redocly CLI
        run: npm install -g @redocly/cli@latest

      - name: Lint API definition
        run: redocly lint openapi.yaml --format=github-actions

      - name: Get API stats
        run: redocly stats openapi.yaml --format=markdown >> $GITHUB_STEP_SUMMARY

This GitHub Actions workflow does the following:

1. It triggers on every push and pull request to the main branch.
2. It checks out your code.
3. It installs Node.js and Redocly CLI.
4. It runs the lint command with the github-actions format. This will automatically annotate any problems directly in your pull requests.
5. It runs the stats command with the markdown format and appends the output to the job summary, giving you a nice report on every run.

This is a powerful way to ensure that your API definitions are always in good shape.

Chapter 4: Practical Example: A Complete Workflow

In this final chapter, we'll put everything we've learned together and walk through a complete, practical workflow. We will:

1. Create a project structure with a multi-file API definition.
2. Create a redocly.yaml configuration file.
3. Lint the API definition using our custom configuration.
4. Bundle the API into a single file.
5. Generate API documentation.

1. Project Setup

Let's create a new directory for our project and set up the file structure.

mkdir redocly-petstore
cd redocly-petstore
mkdir -p openapi/components/schemas openapi/paths

Now, let's create the split API files.

openapi/components/schemas/Pet.yaml:

type: object
properties:
  id:
    type: integer
    format: int64
  name:
    type: string
  tag:
    type: string

openapi/paths/pets.yaml:

get:
  summary: List all pets
  operationId: listPets
  responses:
    '200':
      description: An array of pets.
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: ../components/schemas/Pet.yaml

openapi/root.yaml (our main entrypoint):

openapi: 3.0.0
info:
  title: Petstore API
  version: 1.0.0
  description: A professional API for managing pets.
servers:
  - url: <https://api.petstore.com/v1>
paths:
  /pets:
    $ref: ./paths/pets.yaml

2. Create redocly.yaml

Now, let's create our configuration file in the root of the redocly-petstore directory.

redocly.yaml:

apis:
  petstore@v1:
    root: openapi/root.yaml

lint:
  extends:
    - recommended
  rules:
    operation-summary: error
    no-path-trailing-slash: warn
    tag-description: error

In this configuration, we've defined an alias petstore@v1 for our API and added some custom linting rules.

3. Lint the API

Now, let's lint our API using our new configuration.

redocly lint petstore@v1

You'll see some errors and warnings because our API doesn't yet conform to all our new rules. For example, we don't have tags with descriptions. This demonstrates how you can enforce your own API style guide.

4. Bundle the API

Next, let's bundle our multi-file API into a single distributable file.

redocly bundle petstore@v1 -o dist/petstore.yaml

This will create a dist directory with a petstore.yaml file inside it, containing the fully resolved API definition.

5. Generate Documentation

Finally, let's generate our API documentation.

redocly build-docs petstore@v1 -o dist/petstore-docs.html

This will create dist/petstore-docs.html. Open this file in your browser to see your beautiful, interactive API documentation.

And there you have it! A complete workflow from a structured, multi-file API definition to a bundled file and professional documentation, all managed with Redocly CLI.

Conclusion

In this tutorial, we have taken a deep dive into the Redocly CLI. We started with the basics of installation and core commands, then moved on to advanced topics like configuration and CI integration, and finally walked through a complete, practical workflow.

You should now have a solid understanding of how to use Redocly CLI to:

• Lint your API definitions to enforce quality and consistency.
• Manage your API files with bundle and split.
• Generate beautiful and interactive API documentation with build-docs.
• Analyze your APIs with stats.
• Automate all of this in a CI/CD pipeline.

Redocly CLI is a versatile and powerful tool that can significantly improve your API development workflow. I encourage you to explore its features further and integrate it into your projects.

Further Resources

• Official Redocly CLI Documentation: https://redocly.com/docs/cli/
• Redocly GitHub Repository: https://github.com/Redocly/redocly-cli
• OpenAPI Specification: https://spec.openapis.org/oas/v3.1.0

Thank you for following this tutorial. Happy API building!