How to Generate Automated API Documentation
Hey there! Let's talk about API documentation.
How Does API Documentation Work?
Imagine purchasing a smart device without a manual. You can’t use it. This is how essential documentation is in the API developer's toolkit. API documentation simply provides information about how to use a particular API. Think of it as a user manual for developers - it tells them everything they need to know about how to interact with the API and what they can expect to receive in response.
As a general rule of thumb, good API documentation should be clear, concise, and easy to follow. It should provide examples of how to use the API in different scenarios, along with any relevant code snippets or explanations. The documentation should also include information about any limitations or restrictions of the API, such as rate limits or authentication requirements.
Key Elements of API Documentation
Structure. One of the key elements of good API documentation is a well-organized structure. Developers should be able to quickly find the information they need, whether they're looking for an overview of the API or specific details about a particular endpoint.
Update. Another important aspect of API documentation is keeping it up-to-date. APIs can change over time, so it's crucial to ensure that the documentation reflects the latest version of the API. This means updating the documentation whenever changes are made to the API, and ideally providing a changelog to inform developers of any new features or changes.
Read: How to Use Notion for API Documentation
Generating Automated AI Documnentation
As a company, we had conversations with small and large development teams about how they maintain their API documentation. Out of almost 60 companies, it turns out that the processes were quite heavily dependent on their tech stacks and frameworks.
For example, while 70% of the companies had some form of API documentation, only 15% had it automated in some form. Most companies at best had a postman collection with different common requests they supported. And especially in companies that had APIs consumed by other internal teams. For instance, to power mobile apps or a frontend, the teams simply shared an example curl or postman collection with the team integrating their APIs. And the integrating team would usually have to figure out the API based on that alone.
Another chunk of developers managed hand-rolled swagger files, but these swagger files were almost always out of date with the actual in-production APIs, because it was common that small changes happened to the APIs but the developer never remembered to also update the swagger files.
What is APIToolkit doing about Automated Documentation?
Documentation simply can’t be a manual process. Developers rarely remember to update it. Moreover, even with the teams we interviewed who automated the documentation generation, the documentation quality was usually skeletal at best. Basically, only a few teams went the extra step of including field-level documentation where they explain what different fields meant.
Therefore, the question is:
- How can we have API (Swagger) Documentation that is always absolutely up to date, especially from the perspective of our customers?
- Any automatically generated documentation requires human input to add the domain specific details into the documentation. How can we gently remind and nudge development teams to input and update this info when new fields are added or modified?
- Documentation is collaborative. How can we facilitate even more collaboration?
The journey is a marathon and not a sprint. So, while we have grander goals, at the moment we’re exploring specific solutions to these 3 questions.
Read: How to Analyze API Logs and Metrics for Better Performance
Derive Documentation from Production Traffic
When requests get to your servers, APItoolkit looks into these requests, checks their structure, and shape, checks the fields, their formats, etc, and uses this information to get an idea of what your API looks like. This information is what is used to generate API docs for you. And then this API Docs can then be downloaded as Swagger.
To help you build a model about how this works, let’s look at some example GET request.
// Request 1 GET /user/1
{ "name": "John Dow", "age": 30 }
// Request 2 GET /user/2
{ "name": "Romeo Dow", "age": 25 }
// Request 3 GET /user/3
{ "name": "Julliet Dow", "age": 40 }
--- Etc
APItoolkit would process these requests and learn that the endpoint has a structure that looks similar to:
Endpoint: /user/{arg: integer}/
field type format examples
---
name string /(a-z) (a-z) “John Doe”, “Romeo Dow”, “Julliet Dow”
---
age int int:(25 <= x >= 40) 30, 25, 40
So, APitoolkit builds this insight about your API, which it uses for anomaly detection and other purposes, but especially generating documentation.
2. When we detect new/updated Fields, nudge developers to update the relevant docs.
If you look at the table, you realise that while we have all this automatically generated data, there’s one thing missing: Description
So what we do is simply notify the team or developer, that we detected a new/updated field, and nudge them to add a description via apitoolkit dashboard. So, a user could then add comments to the field as needed, and the table could then look somewhat like:
field type format examples description
---
name string /(a-z) (a-z) “John Doe”, “Romeo Dow”, “Julliet Dow” A name is the legal identifier of an account user
---
age int int:(25 <= x >= 40) 30, 25, 40 The legal age of an account user, calculate from their uploaded date of birth.
3. Support collaboration via comments on docs, fields and shared updates
Now we have documentations and other information for each fields, but then we also want to allow multiple people in a team to collaborate and come to a concensus about information. And this can happen via conversations over comments on any given field.
Apitoolkit is on the journey of helping developers create amazing API documentation with very low effort. And even while some of these functionality are still in progress or in flux, we’re constantly thinking about the bigger picture, and are confident that we will solve this problem of API documentation elegantly, with time.
Check out the AIToolkit features.
APIToolkit is committed to guiding you through managing quality documentation, and we have written some articles on this topic. Take a look:
Also Read
How to Write API Documentation: 10 Essential Guidelines
Incident Management: How to Resolve API Downtime Issues Before It Escalates
API Documentation and Observability: The Truth You Must Know