How to Create Great API Documentation with OpenAPI

So you’ve created an API – now what? You can have the fastest, most reliable API in the world – but it doesn’t mean anything if customers can’t onboard quickly and reliably in a self-service manner.

I’m a big fan of OpenAPI and Swagger. It’s one of the few standards in our industry that integrates documentation tightly into the software development lifecycle. In this article, I discuss the features of OpenAPI you should be leveraging to create amazing documentation for your customers, partners, and ISVs.

OpenAPI in two minutes

If you’re familiar with OpenAPI, you can skip to the next section. For everyone else, here’s a brief rundown.

OpenAPI is a specification for defining REST service APIs declaratively in a JSON (shudder) or YAML format. Using OpenAPI, your dev team defines all of the endpoints your service exposes, including request inputs, response bodies, error messages, required/optional headers, and more.

I’ve used OpenAPI not just as a writer, but as a service developer and engineering manager. Using tools like Postman, you can create OpenAPI specifications prior to writing code – and even generate mock servers against which you can develop tests. It’s a great tool for encouraging shift-left testing in your API dev.

OpenAPI is also great for writing API documentation. As a technical writer, I find that’s one of the best facets of OpenAPI. You can document your team’s APIs using the same format you use to define the API, generate scaffolding code, and run mock servers.

Use OpenAPI throughout the software development lifecycle

The problem with specifications is that they’re usually static documents. Dev teams create them once and then forget about them.

That creates downstream problems for docs. It’s difficult to tell when a codebase check-in has implications for users.

OpenAPI doesn’t solve this problem completely. Method behavior can change in ways that requires clarification for third-party developers. (A good example is additional security constraints placed on methods as a result of previously unknown exploits.) However, using OpenAPI throughout the development lifecycle means you’ll easily pick up key changes such as new versions, additional methods, and changes to request/response parameters.

Select a good OpenAPI editing tool

A technical writer is only as good as her editor. That’s especially true when it comes to OpenAPI.

An OpenAPI spec can become hard to navigate as the API grows. And, of course, since you’re editing JSON or YAML, there’s always a chance (nearly a certainty, really) that you’re gonna produce one or more syntax errors.

Therefore, I recommend finding a good OpenAPI editor. A good editor will perform both JSON/YAML linting as well as provide some sort of visual method for jumping between paths, components, and other elements of your OpenAPI file.

My default editor of choice is Postman. It has solid support for multiple versions of the OpenAPI specification. Version 10 also supports Git integration, which makes it easier than ever to use Postman as your OpenAPI editor while ensuring you never lose unsaved changes.

If you’re not keen on Postman, or want to keep everything in one place, you can find an OpenAPI extension for your favorite code editor. For example, the OpenAPI Editor from 42Crunch for Visual Studio Code gives you syntax validation as well as a navigation panel and a visual preview pane.

Use YAML and multi-line descriptions

If you’re still using JSON for any declarative format like CloudFormation or OpenAPI that supports YAML, an intervention is in order. Your team will save itself a lot of headache moving to YAML.

YAML also makes documentation easier. The YAML format supports multiple styles of multi-line strings. That eliminates including a horrendous series of hard-to-edit escapes in your raw documentation.

Friends don’t let friends write JSON.

Per the OpenAPI standard, you can also use CommonMark Markdown format in fields such as descriptions. Take advantage of this support to add styling and links to your free-form text.

Write a synopsis and give users a roadmap

One potential pitfall with OpenAPI is that, by default, it’ll present everything as a set of loose methods. Tags are a partial solution to this problem (see below for more info). But you should also provide API consumers with use case-specific explanations.

For example, if you’re exposing a product ordering API, what methods must you call – and in what sequence – to place a complete order? Your API flow in this case might look like this:

• Authenticate to the API

• Find a product

• Add product to cart

• Checkout cart

• Complete order

This is where OpenAPI’s info block comes in handy. At the top of every OpenAPI doc is an info block containing meta-information about your API. You can document your API flow here as a mutli-line description property. Alternatively, you can link out to an external document using Markdown syntax that contains How Tos and Walkthroughs for various use cases.

(If you want to go the extra mile, you could provide a link out to one or more public Postman collections that demonstrate the correct API runtime order for your use cases.)

In my experience, this is an area where many API development teams could put in additional effort. Without an API roadmap broken out by use case, you’re forcing consumers to use trial and error to figure out the secret sauce that makes your API usable.

Cross-linking API methods in OpenAPI

It would be handy if you could link to other API paths from the description fields of other paths. Unfortunately, there’s no defined standard for this. Whether you can pull it off depends on what OpenAPI document renderer you’re using. (Swagger UI can apparently support deep-linking.)

OpenAPI 3.0 addresses this pain point with support for links. Using links, you can define that the input for one method – e.g., DELETE /user/ – uses the input from another method – e.g., PUT /user/. This provides consumers with a way to trace the interactions between calls within your documentation.

Group related operations by tags

Another tactic to help developers make sense of your API is to use tags to sort everything by logical groupings. You can use the tags field under each of the paths entries in your API to assign one or more tags using any format you choose. (Yes, spaces are allowed!)

Once rendered to HTML, consumers can navigate your API methods by tag grouping:

Using tags can also make it easier to navigate an OpenAPI specification as a writer! The VS Code OpenAPI extension provides a handy list of tag groups – with clickable operation IDs – in its left-hand navigation panel:

Define payloads as components

Repetition isn’t just bad in coding – it’s bad in technical writing as well. Every repeated sentence represents a potential mistake that you’ll inevitably forget to correct.

Fortunately, OpenAPI has tools to minimize repetition. Using components, you can define object schemas, security credentials, request and response bodies, and headers in a single location. You can then reference these components in multiple API calls.

Define required fields, errors, and example payloads

REST APIs make it easy to dump large, complex objects out as JSON text. That makes life easy for developers. It means returning a response is as simple as serializing an object in your preferred programming language. But it can make life hell for API consumers who don’t know which fields are needed for a successful call.

You and your dev team can provide three things that will make life easier for consumers. The first is marking required request body parameters with the required: true flag. The second is ensuring that every bad API request returns a detailed error message specifying which required values were missing.

The third is example payloads. API paths support an examples section where you can define a sample request body. Every key call in a consumer-facing workflow should have at least one example that will work out of the box for devs getting up to speed on your API. Examples should be consistent and build upon one another throughout the docs.

Conclusion

There’s no sense in creating an API if you don’t teach developers how to use it. Using the tools provided by the OpenAPI specification, you can create powerful, complete documentation that teaches new API consumers how to onboard in an hour or less.

No time to create API documentation yourself? I’ve spent 20+ years helping companies like Microsoft and Amazon expand their developer ecosystems through great docs and training. Contact me below for information on how I can do the same for you!