1. I'd Rather Be Writing
2. Docs
3. Chapter 4: OpenAPI spec and generated reference docs

Redocly tutorial -- authoring and publishing API docs with Redocly's command-line tools

Download PDF

Redocly provides a variety of tools for working with API docs. Using Redocly’s command-line tools, you can split the OpenAPI definition into many sub-files, and then later bundle up the discrete files into a single file during the publishing stage. You can generate your docs into one of the most attractive outputs available for REST API docs, including integration with conceptual topics as well. Redocly also offers more robust developer portals and SaaS offerings that cover the full authoring and publishing lifecycle.

• Background about Redocly’s approach to simplifying the author experience with OpenAPI
• Overview of Redocly products
• Redocly CLI Walkthrough tutorial
  • 1. Install the prerequisites
  • 2. Break up an OpenAPI file
  • 3. Check your OpenAPI definition against rules
  • 4. Preview the Redoc output
  • 5. Bundle up the OpenAPI definition into a single file
  • 6. Combine conceptual docs with reference docs
  • 7. Explore additional features
  • 8. Publish the reference output
• Conclusion

Note that Redocly is one of the sponsors of my site.

Background about Redocly’s approach to simplifying the author experience with OpenAPI

Before Redocly became Redocly, the team worked on a product called Rebilly that included a 22,000 line OpenAPI definition file. Working in such a long file and authoring in YAML or JSON was especially challenging. Not only was maneuvering in a single massive file difficult, one small indentation error would require them to constantly troubleshoot syntax issues. (The single YAML file for all OpenAPI definition elements was analogous to software developers storing all code for an application in a single file — an unthinkable way of working with code.)

When Redocly innovated on their approach to simplifying OpenAPI spec development, instead of putting a graphical user interface (GUI) on top of the OpenAPI code and requiring users to write the OpenAPI definition in forms, menus, and other widgets, Redocly decided on a more docs-as-code approach that aligns with the developer audience.

Redocly developed command-line tools to split the OpenAPI definition into smaller files to make it easier to work with. Files are stored as separate files and referenced through JSON reference tag ($ref) in the main OpenAPI file. Working in smaller files reduces the likelihood of syntax issues and other formatting errors. It also makes it easier to focus on the content.

The CLI tools also let you check your OpenAPI definition against a ruleset to ensure you’re following best practices. You can configure the ruleset with different levels of strictness, either including or ignoring optional best practices in the OpenAPI specification. This linting lets you identify issues in your OpenAPI definition that might not technically be errors but would better if included.

When you’re ready to publish your OpenAPI definition, you can also use a command line tool to bundle the small files up into a single file again.

Overall, Redocly’s approach to simplifying the author experience with OpenAPI is based on the idea that API documentation should be treated as code. This means that it should be written in a plain text format, such as Markdown, and stored in a version control system, such as Git. This approach has a number of benefits, including:

• It makes it easier for developers and technical writers to collaborate on API documentation.
• It makes it easier to track changes to API documentation and roll back to previous versions if necessary.
• It makes it easier to automate the process of building and deploying API documentation.

Overview of Redocly products

Redocly has a variety of products, so let’s first clarify these tools before diving more deeply into the tutorial.

This article will focus mostly on the authoring experience working with the OpenAPI definition using the command line tools. For more details about Redocly’s Developer Portal and Workflows product, see the Products menu on Redocly’s site.

Redocly CLI Walkthrough tutorial

This tutorial will give you a sense of how the Redocly CLI tools work and how to publish the OpenAPI using Redoc. You’ll break up an OpenAPI file, make some changes, bundle it back up, and then publish it with Redoc. The tutorial has the following sections:

• 1. Install the prerequisites
• 2. Break up an OpenAPI file
• 3. Check your OpenAPI definition against rules
• 4. Preview the Redoc output
• 5. Bundle up the OpenAPI definition into a single file
• 6. Combine conceptual docs with reference docs
• 7. Explore the premium version: Redocly API Reference
• 8. Publish the reference output)

The sections aren’t necessarily sequential, but they proceed through Redocly’s tools in a logical way to become familiar with different aspects of the products. Also, the tutorial uses a sample OpenAPI definition related to the OpenWeatherMap API (used elsewhere in the course). Also, the instructions were written using a Mac. There might not be any differences with Windows, but note that Windows wasn’t used here.

This tutorial is a brief exposure to Redocly’s tools only. For more comprehensive documentation, see Redocly’s documentation.

1. Install the prerequisites

Before you can work with the Redocly CLI tools, you need to install them. Node.js is a prerequisite.

1. Install the Redocly CLI:

   npm i -g @redocly/cli@latest
   

   If you get a permissions error, change npm’s default directory:

    mkdir ~/.npm-global
    npm config set prefix '~/.npm-global'
   

   Then add this to your ~/.bash_profile (or ~/.zshrc if you’re using zsh):

    bashCopyexport PATH=~/.npm-global/bin:$PATH
   

2. Verify the installation by checking the version:

   redocly --version
   

For more detailed installation options, including Docker installation, see Redocly’s installation documentation.

If you’re starting a new API documentation project, you might want to use the openapi-starter template, which provides a pre-configured project structure. You can clone it or use it as a template on GitHub. However, in this tutorial, we’ll use the OpenWeatherMap OpenAPI file that we’ve been using in other places in this course.

2. Break up an OpenAPI file

In this step, you’ll break up an existing OpenAPI file into smaller files.

1. Download the openapi_openweathermap.yml file.

   Right-click the file and choose Save Link As. Save it in a folder called redocly_project in a convenient location. This OpenAPI definition is a small OpenAPI 3.0 file for one API in the OpenWeatherMap API. Note that you can use another OpenAPI definition in this tutorial if you prefer. There’s nothing special about this file — it just gives us an OpenAPI definition to work with.

2. Open a terminal, browse to your redocly_project directory, and run the split command:

   redocly split openapi_openweathermap.yml --outDir openapi
   

   This command splits your OpenAPI file into smaller files inside the openapi directory.

3. In a text editor (such as Visual Studio Code), open the redocly_project folder and browse the contents.

   The folder structure will look something like this:

   └── redocly_project
       ├── openapi
       │   ├── components
       │   │   ├── parameters
       │   │   │   ├── id.yaml
       │   │   │   ├── lang.yaml
       │   │   │   ├── lat.yaml
       │   │   │   ├── lon.yaml
       │   │   │   ├── mode.yaml
       │   │   │   ├── q.yaml
       │   │   │   ├── units.yaml
       │   │   │   └── zip.yaml
       │   │   ├── schemas
       │   │   │   ├── Clouds.yaml
       │   │   │   ├── Coord.yaml
       │   │   │   ├── Main.yaml
       │   │   │   ├── Rain.yaml
       │   │   │   ├── Snow.yaml
       │   │   │   ├── Sys.yaml
       │   │   │   ├── Weather.yaml
       │   │   │   └── Wind.yaml
       │   │   └── securitySchemes
       │   │       └── app_id.yaml
       │   ├── openapi.yml
       │   └── paths
       │       └── weather.yaml
       └── openapi_openweathermap.yml
   

   The original OpenAPI definition remains unchanged as openapi_openweathermap.yml. Redocly has extracted each of the paths, parameters, components, and other elements into individual files inside the openapi folder.

   The new openapi.yml file in the openapi directory contains references to all the extracted files. For example:

   ...
   paths:
     /weather:
       $ref: paths/weather.yaml
   ...
   

   The weather path is now stored in openapi/paths/weather.yaml. When you open this weather.yaml file, you’ll see that its parameters are also stored in external files:

   ...
   parameters:
     - $ref: ../components/parameters/q.yaml
     - $ref: ../components/parameters/id.yaml
     - $ref: ../components/parameters/lat.yaml
     - $ref: ../components/parameters/lon.yaml
     - $ref: ../components/parameters/zip.yaml
     - $ref: ../components/parameters/units.yaml
     - $ref: ../components/parameters/lang.yaml
     - $ref: ../components/parameters/mode.yaml
   ...
   

A few important points about working with split files:

• The $ref syntax used to reference external files is standard in OpenAPI, but not all tools support working with split files.
• When generating API documentation, you’ll typically need to bundle the files back into a single file (we’ll cover this later).

You can customize how files are split using options like --separator to control path separators. See the split command documentation for more details.

3. Check your OpenAPI definition against rules

Redocly lets you run a linter against your OpenAPI definition to check for best practices. In this step, you’ll explore the linting capabilities.

1. First, create a .redocly.yaml configuration file in your root directory with these basic settings:

   extends:
     - recommended
   
   apis:
     main@v1:
       root: openapi/openapi.yml
   

   This configuration uses Redocly’s recommended ruleset for linting. It also points to your main OpenAPI file using the proper structure.

   See Configuration file for more configuration options.

2. In a terminal prompt, cd to your redocly_project folder.

3. Run the linter:

   redocly lint
   

   The command checks your OpenAPI definition against the rules. A successful validation looks like this:

   validating openapi/openapi.yml...
   
   openapi/openapi.yml: validated in 11ms
   
   Woohoo! Your OpenAPI definition is valid. 🎉
   

4. To see how the linter identifies issues, let’s introduce an error. Open your openapi/openapi.yml file and remove the license object:

   license:
     name: CC Attribution-ShareAlike 4.0 (CC BY-SA 4.0)
     url: 'https://openweathermap.org/price'
   

5. Run the linter again:

   redocly lint
   

   You now see a warning about the missing license:

   validating /openapi/openapi.yml...
   [1] openapi/openapi.yml:2:1 at #/info
   
   Info object should contain `license` field.
   
   1 | openapi: 3.0.2
   2 | info:
   3 |   title: OpenWeatherMap API
   4 |   description: >-
   
   Warning was generated by the info-license rule.
   

You can customize the linting behavior in several ways:

• Use different rulesets: minimal, recommended, or recommended-strict.
• Adjust rule severity levels: error, warn, or off.
• Add custom rules or override existing ones.

For example, to use the minimal ruleset:

redocly lint --extends minimal

Or to make all warnings into errors:

redocly lint --extends recommended-strict

Before continuing, restore the license object in your openapi.yml file.

4. Preview the Redoc output

Redocly CLI includes a documentation preview server that automatically rebuilds when it detects changes in your OpenAPI files. Let’s see it in action:

1. Run the preview server:

   redocly preview-docs openapi/openapi.yml
   

   You’ll see output similar to this:

   Using Redoc community edition.
   Login with redocly login or use an enterprise license key to preview with the premium docs.
   
   
     🔎  Preview server running at http://127.0.0.1:8080
   
   Bundling...
   
   
     👀  Watching openapi/openapi.yml and all related resources for changes
   
   Created a bundle for main@v1 successfully
   

   For more details, see the preview-docs command.

   By default, you’ll be using the community edition of Redoc. The premium version (Redocly API Reference) includes additional features like the Try-it-out console, enhanced search, and improved performance.

2. Open http://127.0.0.1:8080 in your browser to see your API documentation:

   

3. Test the auto-regeneration feature:
   • Open openapi/components/parameters/lat.yaml
   • Make a change to the description
   • Save the file

   The preview server automatically detects the change, rebuilds the documentation, and refreshes your browser.

4. When you’re done with the preview server, press Ctrl+C in your terminal to stop the preview server.

To use the premium features, you’ll need to authenticate with redocly login or use an API key. We’ll explore the premium version’s additional capabilities in 7. Explore the premium version: Redocly API Reference.

5. Bundle up the OpenAPI definition into a single file

When you’re ready to use your OpenAPI definition with other tools, you might need to combine all the separate files into a single file. Here’s how to create this bundle:

1. Run the bundle command:

   redocly bundle openapi/openapi.yml -o dist.json
   

   The -o dist.json specifies the output file. After running the command, you’ll see:

   bundling openapi/openapi.yml...
   📦 Created a bundle for openapi/openapi.yml at dist.json in 38ms.
   

2. Open dist.json to see the complete OpenAPI definition with all references resolved into a single file.

You can also bundle to YAML format by changing the extension: -o dist.yaml

6. Combine conceptual docs with reference docs

A common challenge in API documentation is combining conceptual content (like getting started guides and tutorials) with reference documentation. Redocly offers several ways to integrate this content. Let’s explore the simplest approach: using the OpenAPI description field with external Markdown.

1. In your openapi.yml file, update the info section, specifically the description field, to reference an external Markdown file:

   openapi: 3.0.2
   info:
     title: OpenWeatherMap API
     description:
       $ref: description.md
   

2. Create description.md in your openapi folder with this structure:

   # Getting Started
       
   Get the current weather, daily forecast for 16 days, and a
   three-hour-interval forecast for 5 days for your city.
   
   ## Authentication
       
   Learn how to authenticate with our API.
   
   # Usage Examples
       
   Interactive maps show precipitation, clouds, pressure, wind around your location.
       
   **Note**: This sample covers the `current` endpoint only.
   

3. Start the preview server:

   redocly preview-docs
   

4. Visit http://127.0.0.1:8080 and notice the following:

   • The description appears in your docs.
   • Level 1 headings (#) create main sidebar entries.
   • Level 2 headings (##) create nested sidebar entries.
   • Content is easier to maintain in a separate Markdown file.

The premium version (Redocly API Reference) provides additional features for conceptual content:

• The <PullRight> tag to add content in the right column.
• The ability to embed API elements like <SecurityDefinitions />.
• More powerful navigation options.

For more complex documentation needs, consider Redocly’s additional solutions:

• Revel for external developer portals
• Reef for internal API catalogs
• Realm for comprehensive documentation platforms

7. Explore additional features

Redoc comes in two versions: an open-source version (“Redoc community edition”) and a premium version (“Redocly API Reference Docs”). The open-source version provides core functionality for rendering OpenAPI definitions with a three-panel layout. The premium version includes additional features such as:

• Try-it console for testing API requests
• Mock server functionality
• Generated code samples
• Advanced search capabilities
• Performance optimizations for large OpenAPI files
• Version switching
• Enhanced schema navigation
• Multiple examples support
• Role-based access controls
• SEO optimizations

For more information, see Premium vs. open source features.

We’ve covered the basics in earlier steps. Now let’s explore some more advanced features available when you authenticate with Redocly. To access premium features, you’ll need to authenticate with redocly login or use an API key.

1. Sign in to app.redocly.com/profile and create a key (from the Personal Keys section).

2. Log in via the CLI.

   redocly login
   

3. When prompted, enter your API key.

   The response should indicate “Authorization confirmed.” See the login command for more details.

4. Start the Redocly preview server:

   redocly preview-docs
   

   Let’s try some of Redoc’s advanced features:

5. Add example code to your description.md file using the PullRight feature:

   <PullRight>
   Example API calls:
   
   ```bash
   # Get weather by city
   curl api.openweathermap.org/data/2.5/weather?q=London
   
   # Get weather by coordinates
   curl api.openweathermap.org/data/2.5/weather?lat=35&lon=139
   </PullRight>
   

6. Enable interactive features in your .redocly.yaml:

   extends:
     - recommended
   
   apis:
     main@v1:
       root: openapi/openapi.yml
   
   theme:
     openapi:
       showConsole: true
       hideTryItPanel: false
       generateCodeSamples:
         languages:
           - lang: curl
           - lang: Node.js
           - lang: Python
   

Key features available in premium Redoc include the following:

• Three-panel responsive design
• Support for OpenAPI 3.1, 3.0, and Swagger 2.0
• Code samples support through vendor extensions
• High-level grouping in side menu with x-tagGroups
• Integration with React applications
• Enhanced customization options through configuration

For additional capabilities like hosted documentation, automated builds, and enhanced features, check out Redocly’s platform solutions.

Yes, I’ll update this section to align with current practices. Here’s my suggested revision:

8. Publish the reference output

So far we’ve been exploring the API reference output from within the preview server. Now let’s publish the reference output for hosting elsewhere:

1. Bundle the OpenAPI definition:

   redocly bundle openapi/openapi.yml -o dist.json
   

2. Create a new directory called redoc and create an index.html file inside it.

3. Add this template to your index.html file:

   <!DOCTYPE html>
   <html>
     <head>
       <title>API Reference</title>
       <!-- needed for adaptive design -->
       <meta charset="utf-8"/>
       <meta name="viewport" content="width=device-width, initial-scale=1">
       <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
   
       <style>
         body {
           margin: 0;
           padding: 0;
         }
       </style>
     </head>
     <body>
       <redoc spec-url='dist.json'></redoc>
       <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"> </script>
     </body>
   </html>
   

4. Move your dist.json file into the redoc folder.

5. To view the output locally, you can use the Redocly CL:

   redocly preview-docs dist.json
   

You can customize your documentation with various configuration options. Common customizations include:

• Theme colors and typography
• Response example settings
• Navigation behavior
• Search functionality

For samples, check out Redoc in production from companies like Docker, Zuora, and others.

Conclusion

Redoc provides one of the most attractive and functional outputs for REST API documentation. The three-column layout, with navigation, content, and examples clearly separated, creates a documentation experience that has become somewhat of an industry standard.

The tool offers several advantages:

• Clean, modern interface
• Support for OpenAPI 3.1, 3.0, and Swagger 2.0
• Extensive customization options
• Command-line workflow integration
• Active development and community support

While Swagger UI remains popular due to its long history in the API documentation space, Redoc has gained significant adoption due to its modern design and feature set. The CLI-based toolset supports a docs-as-code workflow, making it particularly appealing for teams already using version control and automation in their documentation process.

For organizations looking for additional features and support, Redocly’s platform offers enhanced capabilities including hosted documentation, automated builds, and team collaboration features. You can start a free trial here or learn more at Redocly.

About Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.