Defining Mock Data Using OpenAPI Overlays

You shouldn't have to change your OpenAPI to add examples.

Using API mock data is fundamental for producing meaningful documentation, prototyping, and even running tests. About two-thirds of companies using CI/CD pipelines rely on API mock data to run their tests. Being able to store mock data alongside your API description sounds interesting. However, mock data can considerably increase the size of an API description document. Can OpenAPI Overlays help? Stay with me to learn more.

---

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.

---

Mock data is nothing more than information you can use in your API examples. You can generate mock data in a random way. If that's not good enough, you can be a bit more sophisticated and use tools like Faker to create mock data that looks real. Or, you can simply ask AI to generate mock data for you. I don't care how you get your mock data, as long as you get it and use it with your API. One thing to pay attention to, though, is the overall quality of the mock data you generate. The consensus is that the more realistic a mock feels, the better.

Something else to pay attention to is the size of the mock data you generate. Even a simple API operation to get a list of books available on a store can yield a large number of examples. Suppose you have a Book schema with the following definition:

Book:
  type: object
  properties:
    title:
      type: string
      description: Book title.
    author:
      type: string
      description: Author name.
    isbn:
      type: string
      description: International Standard Book Number.
    publishedDate:
      type: string
      format: date
      description: Publication date.
    publisher:
      type: string
      description: Publisher name.
    pages:
      type: integer
      description: Number of pages.
    language:
      type: string
      description: Book language.
    description:
      type: string
      description: Book summary.
    genre:
      type: string
      description: Book genre.
    coverImageUrl:
      type: string
      format: uri
      description: Cover image URL.
  required:
    - title
    - author
    - isbn

A mock list with meaningful examples of books can take space inside your OpenAPI description. If, for example, you want to test pagination, sorting, and other features, you will need a large list of books. An interesting approach would be to include a simple list inside the OpenAPI description and then use an overlay to define a more comprehensive mock list. This approach would give enough information to those who open the OpenAPI document directly, while giving a full context to those using the overlay. How does the overlay work?

The overlay is a document whose goal is to apply a list of actions to the content of an OpenAPI document. With an overlay, you can add content to a specific section of an OpenAPI document, change parts of the API definition, and even remove information from it. So, you can do things like "add a tag to all operations," and "remove all HTTP POST operations," among many other possibilities. Like adding a previously crafted example list of mock books to the response of the operation that gets all the books. The first thing to do is to identify the target inside the OpenAPI document. In our example, we want to find $.paths['/books'].get.responses['200'].content['application/json'] (this is a JSONPath expression, in case you're wondering). Then, we want to merge whatever is already there with the information we provide, which is our example list. Here's what it looks like:

overlay: 1.0.0
info:
  title: Books API Examples Overlay
  version: 0.1.0
  description: Add book examples to the /books GET response.
actions:
  - target: $.paths['/books'].get.responses['200'].content['application/json']
    description: Add a list of books to the GET /books 200 response
    update:
      example:
        - title: "To Kill a Mockingbird"
          author: "Harper Lee"
          isbn: "9780061120084"
          publishedDate: "1960-07-11"
          publisher: "J.B. Lippincott & Co."
          pages: 281
          language: "English"
          description: "A novel about the serious issues of rape and racial inequality."
          genre: "Fiction"
          coverImageUrl: "https://example.com/covers/tokillamockingbird.jpg"

I only included one example book on purpose. Otherwise, you'd have to do a lot of scrolling here, which is not the point. This overlay adds a plain list of example books, but it's easy to imagine having other, more specialized ones. Like, for instance, an overlay that adds non-fiction books only. Or, another one with books in French. In fact, having granular overlays is a good practice. You can combine multiple overlays to achieve the result you need, and you have the freedom to pick which sets of data you need, depending on the occasion.

The single limit to how you can use overlays to define mock data is in the available tools. The advantage I see in this approach is that it leaves the original OpenAPI document untouched. In other words, adding the mocks doesn't change the API definition in any way. And, to me, that's mandatory because you don't need to increment the existing version and potentially impact your API consumers with a large document.

---