TNS
VOXPOP
AI-Aided Coding
On average, how much time do you think you save per week by an AI-powered coding assistant such as GitHub Copilot or JetBrains AI Assistant?
I don’t use an AI coding assistant.
0%
Up to 1 hour/week
0%
1-3 hours
0%
3-5 hours
0%
5-8 hours
0%
More than 8 hours
0%
I don’t save any time, yet!
0%
API Management

Why Your OpenAPI Spec Sucks

A look at three common issues that make your OpenAPI spec fall short and possible solutions for them.
Jun 28th, 2023 6:10am by
Featued image for: Why Your OpenAPI Spec Sucks

A mix of anticipation and dread washes over me as I open a new inbound email with an attached specification file. With a heavy sigh, I begin scrolling through its contents, only to be greeted by disappointment yet again.

The API request bodies lack essential details: the actual properties of the HTTP call, making it impossible to determine expectations and behavior. The empty objects provided, masquerading as request bodies, offer no guidance to API consumers. Moreover, the inadequate specification file hinders the use of external libraries for validation, analysis or autogeneration of output (like API mocking, testing or Liblab’s auto SDK generation).

After encountering hundreds of specification files (referred to as specs) in my role at Liblab, I’ve come to the conclusion that most spec files are in varying degrees of incompletion. Some completely disregard the community standard and omit crucial information, while others could use some tweaking and refinement. This has inspired me to write this post to help you enhance the quality of your spec files. This also aligns with making my job easier.

In the upcoming sections, we’ll go over three common issues that make your OpenAPI spec fall short and examine possible solutions for them. By the end of this post you’ll be able to elevate your OpenAPI spec, making it more user-friendly for API consumers, including developers, QA engineers and other stakeholders.

Three Reasons Why 

You’re Still Using Swagger

Look, I get it. A lot of us still get confused about the differences between Swagger and OpenAPI. To make things simple, you can think of Swagger as the former name of OpenAPI. Many tools are still using the word “Swagger” in their names, but this is primarily due to the strong association and recognition that the term Swagger has gained within the developer community.

If your “Swagger” spec is actually an OpenAPI spec (indicated by the presence of “openapi: 3.x.x” at the beginning), all you need to do is update your terminology.

If you’re actually using a Swagger spec (a file that begins with “swagger: 2.0”), it’s time to consider an upgrade. Swagger has certain limitations compared to OpenAPI 3, and as newer versions of OpenAPI are released, transitioning will become increasingly challenging.

Notable differences:

  • OpenAPI 3 has support for oneOf and anyOf that Swagger does not provide. Let’s look at an example:

In OpenAPI 3, you can explicitly define that the requestBody for a /payments POST call can be one of three options: CreditCardPayment, OnlinePayment or CryptoPayment. However, in Swagger you would need to create a workaround by adding an object with optional fields for each payment type:


This example does not resemble the OpenAPI 3 implementation fully as the API consumer has to specify the type they are sending through a property field, and they also might send more than one since they are all marked optional. This approach lacks the explicit validation and semantics provided by the oneOf keyword in OpenAPI 3.

  • In OpenAPI you can describe many server URLs, while in Swagger you’re bound to only one:

You’re Not Using Components

One way to make an OpenAPI spec more readable is by removing any unnecessary duplication, the same as a programmer would with their code. If you find that your OpenAPI spec is too messy and hard to read, you might be underutilizing the components section. Components provide a powerful mechanism for defining reusable schemas, parameters, responses and other elements within your specification.

Let’s look at the following example that does not use components:


The filter parameter in this example is heavily nested and can be challenging to follow. It is also used in its full length by two different endpoints. We can consolidate this behavior by leveraging component schemas:


The second example is clean and readable. By creating UserFilter and AddressFilter, we can reuse those schemas throughout the spec file, and if they ever change, we will only have to update them in one place.

You’re Not Using Descriptions, Examples, Formats or Patterns

You finally finished porting all your endpoints and models into your OpenAPI spec. It took you a while, but now you can finally share it with development teams, QA teams and even customers. Shortly after you share your spec with the world, the questions start arriving: “What does this endpoint do? What’s the purpose of this parameter? When should the parameter be used?”

Let’s look at this example: