How to Automate API Documentation
Can documentation be automatically updated whenever the API changes?
The majority of teams that own APIs can't keep their documentation up-to-date. That is according to the 2025 State of Docs survey, run by Gitbook. With more than 400 respondents, I find what the survey uncovers interesting. For example, the biggest problem people have is related to keeping API documentation current. Additionally, the products teams need the most are related to updating documentation automatically. So, how can someone make the documentation update whenever there's a change to an OpenAPI document? Stay with me to see what's possible.
This article is brought to you with the help of our supporter, Scalar.
Scalar is a suite of powerful & customizable developer tools to help you at all stages of API development. Create beautiful API Documentation in a notion-like editing experience.
Generating an API reference from an OpenAPI document is something relatively simple to do. There are numerous tools that let you convert an OpenAPI document into an easy-to-browse API reference. What might not be so simple is to automatically update other parts of the documentation, such as a "Getting started" how-to and specific use-case tutorials. To understand how you can create this automation, let's first look at what you have to do manually to keep those elements up-to-date.
A "Getting started" how-to is like a README for your API. It shows potential consumers what they need to start using your API from scratch. It's the place where you tell people how they sign up, how they obtain the credentials they need to use the API, and how they can quickly make their first request. I know I'm probably oversimplifying, but you get my point. So, what are the things that, when they change, influence the content of the "Getting started" how-to? Information on how to sign up to use your API doesn't depend on the contents of the OpenAPI, so that isn't something you should worry about. Obtaining the API credentials fully depends on the type of authentication your API provides. The instructions would not be the same between an API that uses API keys and one that uses OAuth. In this case, any changes to the OpenAPI's securitySchemes can impact how you explain to people how they obtain their credentials. The final element, which has to do with the first request, depends on the content of the API operation you choose as a first request. Usually, you pick an operation that's easy for potential consumers to understand and use. However, if that operation changes, then you need to change the instructions as well.
Now that we know what parts of an OpenAPI document can impact a "Getting started" how-to, let's see how to automate any updates. For that, we'll use markdown templating and automate the generation of the parts of the how-to that can change. Here's an example of the "How to obtain credentials" section:
After you sign in:
- Navigate to "My applications."
- Click "Create new application."
- You will see a new `client_id` and `client_secret`. Copy them.
- Get an access token you can use to make requests. To do that, make a POST request to https://auth.example.com/oauth/token, passing the parameters grant_type=client_credentials, client_id=example_client_id_from_above, and client_secret=example_secret_from_above.Now, copy this markdown and use it as the description of your OAuth security scheme. Yes, the description of your OAuth security scheme will become a how-to on how to obtain credentials. Let's now do something similar with the "Making your first request." Pick the operation you want users to call on their first request, and add the firstRequest tag to it. Now, on the description of this operation, add the information consumers need to learn how to make their first request. After you do that, you have both the credentials and the first request information inside the OpenAPI document. How do you make the information automatically show on the "Getting started how-to?"
To automate the process of updating the "Getting started how-to," you can write a simple script that replaces variables inside the how-to markdown. You could have the following how-to:
# Getting started with the articles API
Follow these steps to start using the articles API.
## How to sign up
Create an account to access the developer portal:
- Go to: https://developer.example.com/signup
- Fill out the registration form.
- Verify your email address.
Once registered, sign in to access your dashboard.
## How to obtain credentials
${howToObtainCredentials}
## How to make your first request
${howToMakeYourFirstRequest}Notice that we're using two template variables. The goal is that the ${howToObtainCredentials} variable is replaced with the content from the securitySchemes description. Similarly, the ${howToMakeYourFirstRequest} variable is replaced with the content from the description of the operation you tagged as firstRequest. Writing a script that automates replacing the content feels relatively simple, and it can be executed during build time. This makes the contents of the "Getting started" how-to automatically update whenever there's a meaningful change to the OpenAPI document.
You can automate any other relationship between the OpenAPI and other parts of the documentation. What I showed here was just an example of how the automation can be set up and what results you can expect. In the end, what matters is that you feel more confident in how documentation aligns with your OpenAPI document.