Using Redocly

by Robert Delwood, a Lead API Documentation Writer

OpenAPI is the standard now for writing API documentation. The format is intended to describe the technical aspects of endpoints and API suites. It is not intended to be a graphical or visual representation of the suite. For that, you will need a visual rendering tool. I like Redocly.

The following topics are available:

· Installing Redocly

· Using Redocly

· Editing and Viewing OpenAPI files

Redocly is a visual rendering engine for OpenAPI files by the company of the same name Redocly (Redocly.com). The engine renders a well-formed OpenAPI file (either .yaml or .json) into a graphical user interface. The rendered interface is clean, smartly laid out, modern-looking front end, is HTML, CSS controlled, and versatile and customizable. What’s there not to like? The engine comes with a series of command line tools supplementing the engine.

It’s meant to be used as a presentation and editing tool. For presentations, Redocly can either be run directly on a web site, or, more commonly, convert the OpenAPI to HTML. It produces a standalone, double-clickable HTML file. This file is identical looking to the version rendered directly from the tool. The HTML file can be sent to the company’s web site, or to clients. This offers a lot of flexibility.

As an editing tool, it can be set to run as a background process and will always render the latest version of OpenAPI file. This is useful during document edit cycle, to see your current changes, or see what the result is like. Personally, I don’t understand how you cannot see the progressive changes during editing.

Regardless of how the file is edited or created, with the OpenAPI file saved and available for use, Redocly can then be run on the file, rendering it. The following are procedures are required to install and to run Redocly.

The Installing Redocly section needs to be run only once.

The Using Redocly section can be run as many times as needed, presumably daily during editing and for verification of the changes.

Installing Redocly

Use the following procedures for the Redocly installation. The procedures are the same for Windows and Mac. These procedures look long, but really they’re just three commands; most of it is explanation. These are needed to be done only once.

Installing npm and node.js

Verify npm and node.js are installed first. In a command window at any level:

Enter: npm -v

The package npm is installed if a version number is returned. For example: 8.6.9

The package npm is not installed if an error message is returned. For example: ‘npm’ is not recognized as an internal or external command, operable program or batch file

Enter: node -v

The package node.js is installed if a version number is returned. For example: v18.16.0

The package node.js is not installed if an error message is returned. For example: ‘’Node’ is not recognized as an internal or external command, operable program or batch file.

Both packages need to be installed.

If both packages are installed, skip down to Installing Redocly below.

If at least one is not installed, use the following procedure:

1. Download the installation package. Navigate to the Node main page (https://nodejs.org/en).

2. Select Download Note.js (LTS). This downloads the latest version. The file name will be like node-v20.17.0-x64.msi.

3. Launch the downloaded file. Follow the screen instructions accepting all the default values.

There may be several command windows that run. Accept any that show.
The install may take a moment. Accept all the defaults, and ignore any errors or warnings displayed on the screen. The installer has to be everything to everyone and so, not all cases may apply to your set up.
A reboot may be needed. Follow screen instructions at the command prompt.

Additional help and instructions may be found at: https://docs.npmjs.com/downloading-and-installing-node-js-and-npm.

After installation is complete, test the installation.

1. Close the command window and open a new command window at any level:

2. Enter: npm -v

3. Enter: node -v

Both should show versions numbers, which indicates the packages has been successfully installed.

Installing Redocly

Redocly can now be installed. In a command window at any level:

1. Enter: npm i -g @redocly/cli@latest

2. Test the installation. From a command window at any level, including the already-opened command window, enter: openapi –version
Redocly is installed if a version number is returned. For example: 1.0.0-beta.95

Using Redocly

Redocly is now ready to use. To render an OpenAPI file, use the following procedure.

1. In a command window in the same directory as the YAML file, enter: openapi preview-docs <fileName>
The <fileName> is the OpenAPI source file. For example: openapi preview-docs petstore.yaml

2. Open in a browser at the location: http://127.0.0.1:8080. The page renders.

3. When done, either close the command window or terminate the server process with Ctl-C.

You may use any OpenAPI file, YAML or JSON. It must be well-formed, meaning there can be no structural errors. Debugging an OpenAPI file can be difficult. For that reason, I suggest going slowly, making a few changes at a time and then checking the results with Redocly. Developer IDEs, such as Microsoft Visual Code or Jetbrains Intelli provide error checking during editing. I recommend using one of these tools for that reason. They will immediately point out many errors. Otherwise, any editor capable of saving as plain text can be used. This includes NotePad, NotePad++, and even Microsoft Word.

For the first attempt, I recommend downloading an existing OpenAPI file. It’s easier to learn and to modify a file that works. One secret of development is to always start from something that works. Keep in mind that OpenAPI is a strictly enforced specification, meaning that there are right and wrong ways to format the information. Redocly will report errors. Of course, any rendering tool report errors, too. You can download the following sample files

SmartBear Petstore.yaml. The Pet Store sample is probably the most famous example, with Swagger and then SmartBear maintaining it. It is a good download with many samples built in:
https://redocly.com/_spec/openapi/petstore.yaml?download

Redocly Museum.yaml. This is Redocly’s OpenAPI example. It is a good download with many samples built in. It is also open source, so you can suggest changes to the official file:
https://redocly.com/_spec/docs/openapi/museum-api.yaml?download

Any OpenAPI file may be used and a copious number of existing examples can be found with a simple web search. In addition, GitHub examples may be used with a little more with copy and paste steps. I recommend you keep to YAML format, as it’s easier to read and to edit, and use only version 3.0.0 or later. Do not use version 2. The version number can be found in the first line of the OpenAPI file. For example:

openapi: 3.0.3

Editing and Viewing OpenAPI files

This is where the simplicity of this process comes in. It is simple and powerful.

With the processes above installed, the file can be edited.

Open the OpenAPI file.

Make your edits. The key is the description tag will. This will be the tag you get to edit the most. Make your changes within this area, in the diagram below in lines 619–621. Of course, you won’t be restricted to these lines. The area will expand or shrink as needed.

OpenAPI is a structured language, so that indentions matter. The content in this instance must be indented 20 spaces. An IDE such as Microsoft Visual Code or a text edit like NotePad++, as examples, handle the indentation for you. That is, if you use a Return at the end of a line, either of those editors automatically place the cursor in the correct column of the next line. This is the first major advantage, the effortless editing. Other editors such as NotePad, does not place the cursor automatically. You will be responsible for manually identing each line. That is annoying even for a single line, and is a good case for using a developer IDE.

At any time, you can test the output. Save the edits and the file. Switch to the browser window running Redocly. The page should refresh in three seconds, allowing you to see the change. If it doesn’t automatically refresh, press shift and click the browser’s page refresh button at the same time. This clears the cache and allows for a clean refresh. This is the second major advantage, the convenience of rendering. You can check the progress at any time, as often as you like.

Text formatting can be either Markdown and/or HTML. Markdown has become popular for its lightweight and unintrusive notation. The following are examples of Markdown. Markdown guides can be found on the Internet.

I encourage Markdown be used first and as much as possible. However, Markdown is severely limited at times. In those cases, feel free to use HTML. This includes for detailed tables and links, too. I use the HTML new line tag <br> for better line control. The following is an example of HTML within a description tag.