Documentation-driven API Design
Can you design an API just by writing plain documentation?
Wouldn't it be great if you could simply write the documentation for an API operation and automatically get an OpenAPI document? Well, this is now possible thanks to AI. I did an experiment where I was able to have an API mock server starting with nothing more than a brief description of an operation. Follow 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.
The great thing about API Design is that you can do it in many ways. You can design an API by first creating a collection of operations that you can test and share with stakeholders. Or, you can start by prototyping your API using OpenAPI directly. Or, you can start by writing what your API will do and have it automatically translated into a machine-readable definition. I tried this last approach and I can tell you that it seems to work well. Let me show you what I did. I started with a simple description of what I wanted my API to be like. Then, through a series of simple steps, I managed to have a mock server up and running.
The first thing I did was write down a description of my fictitious API. I thought of creating an API to search articles. My description was simple enough and easy to understand. It could be something you'd hand out to developers asking them to implement it for you. The description reads like this: "A REST API that lets consumers search articles by their title, tags, and published date. The API lets consumers sort the results by each one of the parameters in ascending or descending order." Simple and easy to understand, right? There are many unspecified elements but, as an example, this is enough.
I took this description and asked ChatGPT to generate a how-to to help consumers learn how to use this API. I didn't want it to generate an API reference because you can do that easily without AI. Instead, I wanted to see how well it could understand my description and get a how-to document I feel I could have written myself. I found the result impressive. It included an overview of the API operation to search articles, documentation about all possible query parameters, an explanation of how to use sorting, example requests covering different needs, and even information about error handling. It's more than what I was expecting!
Now, with this how-to, it's time to convert it into an OpenAPI description document. To do that, I asked ChatGPT to "generate an OpenAPI description document for an API that has the following documentation," and copied the generated documentation. The result was a full OpenAPI document complete with descriptions and examples. From here, I can do almost anything. I chose to create a mock server because it's what lets me get feedback from stakeholders. I took the OpenAPI document to WireMock, an open-source and cloud API mocking solution. It took me less than five minutes to sign up, create a new mock API, import the generated OpenAPI document, and have the mock server up and running!
After I imported the OpenAPI document into the mock server was immediately available for me to use. I made a GET request to the /articles path and got a response with the examples that had been generated by ChatGPT. Not bad. From here I could continue and add my own examples. Or, I could connect the mock to a data source to get realistic responses. Or, I could even create a stateful mock that would let me create articles and then find them through the search operation.
In summary, this sounds like a viable approach to designing an API from scratch when you have little knowledge of OpenAPI and don't want to get your hands too dirty. You can simply write what you want your API to do and end up with a running mock server just like I did.
Cool