Documenting Examples using OpenAPI

Is there any advantage in using OpenAPI to document examples?

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?

---

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.

---

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.

And, the easier it is to see and use those examples, the better. That's why I chose to embed the examples as much as possible directly into the OpenAPI description. Instead of providing separate documentation just for the examples, I tried to use the same document for both the API reference and the examples. I know, some of you might say that examples are a part of the API reference. Well, they can be, but they can also be documented and shared separately.

The versatility of OpenAPI allowed me to create and add examples for different parts of the API. Let's look at some of those elements and how adding examples increases the overall value of the API reference. From request parameters to response payloads, offering examples adds a lot of color to an otherwise pale OpenAPI description. The easiest thing I did was create an example for a query parameter. If sometimes overlooked, even the simplest query parameters can generate confusion so, offering examples has its value.

To create query parameter examples I used the examples field under the operation I was interested in. I could have used the example field (singular) to add just one example, but I want to add more than one. Here's how adding a few examples looks like (in YAML):

(...)

		examples:
		  articleExample:
		    summary: An article title
		    value: Documenting Examples using OpenAPI
		  bookExample:
			  summary: A book title
			  value: Building an API Product

(...)

The more examples you create the better consumers will understand how to work with your API. From your perspective, however, having lots of examples might make the maintenance of the OpenAPI description somewhat complicated over time. One handy way of keeping all examples close together—and being able to reuse them—is to use example references. Following the sample above, instead of writing the examples directly in place, you'd add them to the components section and simply reference them wherever you need.

(...)

	  examples:
	    articleExample:
	      $ref: #/components/examples/article-example
	    bookExample:
	      $ref: #/components/examples/book-example

components:
  examples:
    article-example:
      summary: An article title
      value: Documenting Examples Using OpenAPI
    book-example:
		  summary: A book title
		  value: Building an API Product

(...)

Now, whenever I want to use the article-example I can simply reference it from anywhere in the OpenAPI document. Well, not technically anywhere, but everywhere I can describe an example. Which is a lot, by the way. Some places include the parameters object, which I showed before, the request body, and also the response body. Taking into account that they can all use references, there's a lot you can do with examples on your OpenAPI document. Let's look at an example of something more complex, like a list of articles.

(...)

components:
  examples:
    article-list:
      summary: A list of article titles
      value:
        - Documenting Examples Using OpenAPI
        - Common Risks Associated with APIs
        - Using OpenAPI to Document the API Operations You Consume
        - The Missing Link between AI and APIs
        - How Documentation Affects API Quality

(...)

Now, suppose you want to build a list of article examples, with not just their titles but also a link to each one. That shouldn't be too hard. Let's expand on the previous example and see what it would look it.

(...)

components:
  examples:
    article-list:
      summary: A list of article titles
      value:
        - title: Documenting Examples Using OpenAPI
          link: https://apichangelog.substack.com/p/documenting-examples-using-openapi
        - title: Common Risks Associated with APIs
          link: https://apichangelog.substack.com/p/common-risks-associated-with-apis
        - title: Using OpenAPI to Document the API Operations You Consume
          link: https://apichangelog.substack.com/p/using-openapi-to-document-the-api-operations-you-consume
        - title: The Missing Link between AI and APIs
          link: https://apichangelog.substack.com/p/the-missing-link-between-ai-and-apis
        - title: How Documentation Affects API Quality
          link: https://apichangelog.substack.com/p/how-documentation-affects-api-quality

(...)

Each example becomes an object with a title and a link. It's as simple as that. In fact, examples can be anything. You can even have examples that are referenced as external documents. That would work well for things like images and other binary files. There are plenty of possibilities around using examples inside OpenAPI as they enrich the experience of consumers.

The best thing, I think, is that most API reference renderers show examples properly. The ones I use even let you pick which example you want to use there's more than one. With that, a consumer can quickly understand how an API response would look like in real life. Speaking of real life, examples also add value to API testing. Popular API mock tools can pick the examples you add to your OpenAPI and use them to simulate a real API. Consumers can not only see the examples documented but can also test the API and see realistic responses.

---