Documentation-driven API Design - by Bruno Pedro
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.
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.
