Automated API Documentation: Everything You Should Know
7 min read
Walker Rowe

Freelance: API documentation and other IT Writing

Automated API Documentation: Everything You Should Know

API documentation helps developers understand and use APIs effectively. 

With automation, it’s easier to generate accurate and up-to-date reference materials. But some parts of documentation—like guides and tutorials—still require a human touch. 

In this article, you’ll learn about the components of API documentation and the challenges of automation, as well as discover tools that streamline the process.

What are the different types of API documentation?

There are two types of API documentation:

  1. API guides
  2. API reference

The usual practice is to auto-generate the API reference and manually write the API guides.  

API guides or documentation refers to free-form documents written by hand. Examples include getting started guides, FAQs, tutorials, and documents showing how to do common tasks, like creating a sales order.

API reference pages show all the details of an API. They have a fairly fixed format since they always show the same information regardless of the software publisher’s product. The reference provides the information a programmer needs to use the APIs, such as: 

  • The endpoints of an API, e.g. https://website.com/dosomething
  • The operation type (e.g., GET, POST)
  • The parameters together with an explanation of what those parameters mean.

Important note: In this article, we are talking about REST APIs that a programmer can access over the internet.

Why do we need to automate documentation?

Unless an API is very small, anyone who tries to write API reference material by hand will quickly encounter the following difficulties::

  • The documentation would quickly get out of sync with the code as programmers add more features to their system, meaning new parameters and APIs.
  • There is no automated way to check spelling and logical consistency like there is in the software build. A software build is when a software development team compiles all of its code into the final product. That usually happens every couple of weeks as the team works on short-term milestones.
  • The API technical details can be very large—even hundreds of lines long. It would be very tedious to write this by hand for anything other than a system with just a single API endpoint and a small number of parameters.

This complexity, coupled with the need to ensure that documentation accurately reflects code, suggests the documentation should be based on an object that is code. And not free-form text.

Programmers call this object a specification. The standard used to create that specification is called OpenAPI, formerly called Swagger.

The OpenAPI Specification (OAS) describes every detail of the API and provides space to document the meaning of every parameter, header, error message, etc. The text description can also include markdown, which means it can generate tables, bulleted lists, links, and even allow images.

Here are all the items that describe an API:

  • Endpoints: e.g., /createSalesOrder, /moveInventory
  • Description: an explanation of what it does
  • Operation: POST, GET, PUT, DELETE
  • Security and other headers: API Key, oAuth2, content-type
  • Attributes: i.e., the JSON body like {“id”: 123, “amount”: 456}, plus the type and description for each
  • Parameters: e.g. ?city=chicago&weight=243&volume=567
  • Error codes: 500, 301, 201
  • Sample data

So, the OAS serves two important functions. Programmers can use it to write code since it is an exhaustive description of the entirety of the API. And tech writers can use it to create documentation.

An example of automated API documentation

The easiest way to understand API documentation is to look at an example.

Below is the Swagger Petstore OAS. You can see this in the online Swagger Editor.  The OpenAPI Initiative developed the Petstore Open API example to demonstrate how to use OpenAPI, so most programmers are familiar with it.

On the left is the OAS. The auto-generated documentation is on the right. 

The idea is that as you update the spec on the left, it creates the documentation on the right.

First, we will look at the right-hand side, which is the generated web page. Then we will look at the code.

The generated web page

Most API documentation systems will have a screen where you upload the OpenAPI YAML or JSON file, or pull it directly from GitHub. That will then generate the documentation. 

Specifically, it will create a web page showing every API endpoint and the parameters needed to use it.

In the example below, we have the operation POST to the endpoint /pet. This is how you add a pet to the pet store. You fill in the request body in JSON format and then send a POST request to the web address https://somewhere.com/pet. Below, you can see a portion of the JSON body, the payload, which describes the pet.

Notice there is also a Try it Out button that allows programmers to try the API online.

Programmers can use many different languages to call APIs. But the way you call APIs is always the same—it requires the same elements (header, parameters), operations (GET, POST), and handles the response the same way by converting it to JSON and checking for an error code.

This means a programmer does not need to write their own program but can simply copy a boilerplate example.

OpenAPI knows this, so they provide this boilerplate code in Python, NodeJS, curl, and other common programming languages.

The OpenAPI Specification (OAS)

The OAS is a document in YAML or JSON format.

Both contain the same information, the only difference is they use a different format. JSON uses curly braces {} and brackets [] to delimit objects. YAML uses colons (:), spaces, and dashes (-). YAML is more compact, so it’s shorter, while a JSON document can be so large that you usually need a special editor to work with it.

In the YAML format, the Petstore spec is 806 lines long. That’s for just 13 APIs. Since the document is hierarchical, you can collapse it with different editors to make it easier to see each API or section.

Below we have collapsed it to list only the API titles and other section headers.

Here we see a portion of the definition for the /pet endpoint. Remember that the OAS document is a combination of descriptive text and the formal definition of the API. That formal definition must follow precise rules regarding format and content.

Regarding descriptive text, the programmer writes a one-line summary in the summary attribute and a slightly longer description.   

Continuing, the rest of this specification includes the schema, the endpoint, the operation type (PUT, GET), the required headers, and the error codes and messages. (Schema refers to the attribute name and type , plus an optional description.) 

A small section of the Pet schema is shown below. 

Notice that in the Pet Store example, there is no description attribute. It’s optional. So, whoever wrote this YAMP OAS spec decided that petId is self-evident and did not need further explanation. This would be spelled out in a more complicated system, such as a medical or industrial application.

How to modify the OAS to automate documentation

How do we allow developers and technical writers to work on the specification and documentation? 

By separating the text portion of the spec from the definition section. Unfortunately, the document isn’t designed this way.

Additionally, the spec is under software code control that requires a check-in and check-out process to modify it, further complicating that goal.

Normally, a tech writer would not be allowed to edit the OAS for several reasons.

Because it’s computer code, a tech writer adding to the documentation could break the code section. 

Also, the development team operates on a short schedule of iterations that can be as short as two weeks. A tech writer needs more time than that to complete their work. The tech writer couldn’t check out the spec for longer than two weeks as it would block the software development cycle. 

There’s an obvious solution to this situation: provide an extension to the OAS where the tech writer can write documentation without interfering with the development process. In other words, make the spec refer to the documentation as an external object separate from the code sections.

Then, changes to the documentation would get pulled into the generated HTML API reference at whatever frequency the tech writers want. And the developers can update the code sections without overwriting the tech writer’s work.

The ReadMe approach to automated API documentation

ReadMe has developed a workaround to handle the inherent difficulty described just above. Our approach does not violate any OAS rule or break any automation. Yet it cleverly allows the tech writer to extend the documentation in the OAS without modifying it.

Specifically, ReadMe lets the tech writer effectively modify the description and summary attributes in the OAS, by maintaining that outside the specification. In the interface layer, the reader sees the modified text descriptions while the rest of the HTML-generated API reference page remains the same.

This does not in any way impair the automated API workflow. Nothing changes for the programmers. And the tech writer is allowed to enlarge or clarify the descriptive part of the spec.

To explain, take a look at a portion of the spec shown below.

In the ReadMe API editor, the tech writer can modify the summary and description attributes by simply typing over what is already there. This allows them to write a more exhaustive set of instructions than the programmer. 

Plus, the description attribute can include markdown, so not only can the writer make the description longer, but they could also add a table, bulleted list, links, graphics, etc.

In the OAS, the attribute operationId is a name assigned to each endpoint/operation combination.

If operationId already exists, ReadMe won’t overwrite the summary or description whenever the developers update the rest of the document. This preserves the work of the tech writers while adding the changes made by the developers.

Note that the tech writer cannot update the attribute-level attribute description. The only way to change that is the old-fashioned way, which is to relay those changes to the developers and ask them to fill it in.

Usually, the developers will already do this when the parameter changes. But the tech writer may be tasked with reviewing and code-testing the instructions. They would then identify any missing information, usually by attempting to write code examples themselves based on the instructions. In doing so, they can uncover information that has been left out.

Simplifying API documentation without compromising workflows

To sum up, API documentation refers to: (1) the API guide that you write by hand and (2) the API reference which is automatically generated from the OAS written by the programmers.

However, there is a built-in complication to this design. The documentation and the technical specifications that rigorously define the API are in a single document. That makes it difficult (if not impossible) for the tech writer to expand and clarify the instructional part of the specification.

Logically, this problem wouldn’t exist if the designers had structured OpenAPI differently so that the OAS included links to documentation written in a completely separate document.

Fortunately, ReadMe’s documentation tool overcomes this challenge in a way that improves the documentation but doesn’t interfere with the programmers’ build, release schedule, or workflow.