Using openapi-cli: intro

Before we jump into the usage of this mysterious tool with way too generic name, let me give you an introduction.

There are many tools for supporting API design via OpenAPI description documents. You can check the list here.

The most common tasks are:

• dereferencing
• linting
• reference documentation preview and/or generation

I talked about dereferencing not long ago. In short, it’s needed to produce a final OpenAPI description doc from more DRY and granular schemas. You can read more about the process here. One of the tools that can help you is json-schema-ref-parser.

Linting is used to check OpenAPI description doc for errors and style guide violations. Spectral comes to mind; Arnaud Lauret has a great talk about using it for design reviews.

SwaggerUI is the most common choice for reference documentation generation. If you need something more aesthetically pleasing you can try Redoc or RapiDoc.

But there is a tool that combines all of these and more: welcome to openapi-cli (GitHub, docs). It supports both OpenAPI 2 (fka Swagger) and OpenAPI 3; support for 3.1 is coming soon. At the time of the writing, the tool’s version 1 is still in beta phase, so keep it in mind. But I’m fairly confident in using it anyway. Why? Two reasons.

First of all, it’s developed by the same team as the famous Redoc, so you already know how reference docs look like =) Redoc is famous. You cannot read a book or attend a conference without seeing it mentioned by someone. A lot of people use it, so it would make sense for a openapi-cli to be developed further.

The second reason is stated on the team’s site: “built because we needed it”. All tools developed by Redocly are used in the other company of its founder, Adam Altman, Rebilly. These tools weren’t created in vacuum; they are constantly dogfooded by the developers whose primary business is making good APIs. By the way, check their api definitions for an inspiration on how to structure description doc development.

So, in this series of articles I’m gonna write about my experience of using openapi-cli.

We gonna go through themes:

• using openapi-cli for API exploration
• basic API doc structuring and preparation (dereferencing, previewing, linting, handing off results)
• advanced topic: preprocessing
• advanced topic: custom linting rules
• advanced topic: decorators

And while I’m writing next posts (hehe), install and play with it!

P.S. It’s a pity that Redocly team isn’t very active about advertising themselves. While everyone knows and praises Redoc, openapi-cli isn’t that well-known. Maybe the team wants to finish the beta first? Anyway, I was using it for almost a year, and I think it’s time to break the silence and give it some public love!