Is AI the End of API Documentation?
Is AI the End of API Documentation?
How can you take advantage of AI to enhance your API documentation?
Writing API documentation is something not everyone enjoys. Most people try to automate the documentation process as much as possible. If one of the promises of AI is the ability to generate text, does that mean that the manual process of writing documentation is dead?
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 a machine-readable definition is something considered basic nowadays. Creating a chatbot that can answer questions about the API is also quite easy to build. Generating context-aware how-tos and tutorials for an existing API is also doable with the help of AI.
If everything can be easily automated what is the role of people that spend their time writing API documentation? Can AI replace all activities related to producing API documentation?
In 2016 I built the very first API assistant using natural language understanding (NLU) and a naive neural network to provide unsupervised learning (see demo video). The Hitch API Assistant had the ability to connect to any OpenAPI definition and answer any questions about the API, from a consumer perspective.
Whenever it couldn't find an answer it would fire a HITL (human-in-the-loop) through a support request. It would then use the support response to learn and be able to answer more questions autonomously.
This was eight years ago. There was no OpenAI, ChatGPT, LLMs, or any of the other AI-related solutions there are today. Today the possibilities are orders of magnitude higher.
Today the possibilities are endless. Almost unrealistic, looking back to what you could put together eight years ago. Let's look at some of the things you can put together with the help of AI.
The first one that comes to mind is related to code generation. Why have generated code that looks the same to all consumers? Instead, you can use AI to understand the needs of a specific consumer and generate the code for a specific integration. The code can be generated using the desired programming language, to fulfill a specific use of your API, avoiding all the requests that will never be used.
Another example where AI can shine is with tutorials. You can let potential consumers share what they're looking for and automatically build a full tutorial based on their needs. Instead of having generic tutorials or, trying to figure out what the most wanted tutorials will be, you can have fully personalized pieces for every singular need. These tutorials can be as detailed as you want and offer code samples and guided instructions tailored to the specific requirements.
A third area where AI can be helpful is in keeping documentation up-to-date with any changes you introduce to the API. I recently covered a scenario where introducing changes can affect your documentation.
Whenever you introduce a change to your API there's a natural mismatch between what it does and what the documentation says it does. While it's straightforward to automatically update your API reference whenever you introduce changes, you can't say the same about the other parts of your documentation.
With the help of AI, you can synchronize those changes to updates in your API documentation. The whole process can be fully automated and can even trigger notifications to consumers who want to be aware of any changes.
One final area where AI can be helpful has to do with the link between usage patterns and documentation. You can use AI to detect patterns in API usage. If you detect difficulties in using certain parts of your API you can craft an automated tutorial and send it to the affected consumers.
All these areas show me that AI isn't definitely the end of the API documentation. In fact, AI can enhance API documentation to the point where it becomes fully tailored, customized, and useful to each specific consumer.
AI also needs to feed on something to produce its output. That something, in the case of APIs, is a machine-readable definition. Without an OpenAPI, AsyncAPI, or any other machine-readable definition you won't be able to take full advantage of what AI can offer.
The evolution of AI related to API documentation since eight years ago is staggering. However, the common ingredient is still the machine-readable definition. Eight years ago we were still evangelizing people to use OpenAPI and other similar standards. Today, that's not the case anymore so, what's keeping you from taking full advantage of what AI has to offer?