Documenting Examples using OpenAPI - by Bruno Pedro
Examples make explanations easier to understand. For example, understanding the process of designing an API isn't easy. But, once you see someone do it before you, everything feels easier. Suddenly, you just have to copy what you see and adapt it to your own situation. In the case of API, examples are a helpful way of showing how requests and responses can look in a real scenario. So, how can you use an OpenAPI document to describe your API's examples?
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.
I've been spending a big chunk of my work days understanding how a particular API would work in a real situation. To do that I simulated how consumers would use the API and, in particular, the requests they would make and the responses they'd get. I started by manually using Web sites that offer features similar to what I'm working on. I then inspected the requests sent from my browser and the corresponding responses. With that information, I was able to put together a plausible example of what a request and a response to this new API would look like.
The example I came up with feels like something you'd get from a real API. It doesn't feel like fake information, which is what you often get using tools such as Faker. Having realistic examples is important during the API Design stage. You want to share your API mock with stakeholders to get feedback about your design. The last thing you want is to get biased feedback because the responses don't look real. For a stakeholder, the closer to reality your API feels like, the better.
