Using OpenAPI and 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
• 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.

Redocly's meant to be used as a presentation and an editing tool.

• For presentations, Redocly can either be run directly on a web site, or, more commonly, convert the OpenAPI to HTML. It can produce 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, Redocly 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 editing can be done without frequently seeing the changes just made. Authors may decide they don't like the spacing, the line breaks, or even the wording once they see it rendered.

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 procedures are required to install and to run Redocly.

Installing Redocly

The?Installing Redocly?section needs to be run only once.

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.

Installing npm and node.js

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

Enter:?npm -v

• The package npm is installed if a version number is returned. For example: 8.6.8
• 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.

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

With both npm and node installed and confirmed, Redocly can now be installed.

Test that Redocly isn't already installed.

1. Open a command window at any level.
2. Enter:?openapi --version

• The package Redocly is installed if a version number is returned. For example: 1.0.0-beta.95

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

If Redocly is not installed, use the following procedure:

1. Open a command window at any level.
2. Enter:?npm i -g @redocly/cli@latest
3. Test the installation. Open a command window at any level, which could be 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

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

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

1. Open 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:?https://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 or indenting 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 Intellij provide better and some real time error checking during editing. I recommend using one of these tools for that reason. I like Jetbrains Intellij. They will immediately point out 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: https://redocly.com/_spec/docs/openapi/museum-api.yaml?download

It is also open source, so you can suggest changes to the official file.

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        

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.

1. Open the OpenAPI file.
2. Make edits. I suggest making only a few edits at a time.
3. Review the changes in Redocly. Use the first three steps in the Using Redocly section to run Redocly as see changes. After running Redocly, you can keep that browser window open. On subsequent file changes, it'll either automatically update or you can use Shift-Refresh to force an update.

Editing OpenAPI files

This is brief, very brief, tutorial on editing an OpenAPI file.

The key is the description tag. This will be the tag you get to edit the most.

The description tag comes in two formats.

A line with description: (ending in a colon) represents a single line.

description: User to create.        

A line with description: |(with colon-space-pipe) represents multiple lines. Add a return after the pipe and indent on the next line, and reset becomes free formed text. You can format it as you want to. Make your changes within this area, in the diagram below in lines 619–621.

??????? description: | 
            User to create. 

            You may add lines here.        

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 indenting 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 unobtrusive 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 limited at times. It does particularly bad with tables and links. 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.