Benefits of Using the OpenAPI (Swagger) Specification for Your APIs

With software products becoming just a bunch of micro-services and third-party APIs mashed together, it's more crucial than ever to get their structure in order.

GraphQL already did this at its inception by coming up with a whole specification that describes how APIs of its type should behave. In the RESTful API landscape, things were a bit more wild west. However, even if not all backend devs know it, there are a number of specifications for REST APIs as well.

One of the best known is the OpenAPI Spec, or OAS for short.

Enter OpenAPI

The OpenAPI specification was known as Swagger until version 3.0 was released in 2017, when it was renamed to OpenAPI. It’s a language agnostic way to describe a RESTful API, that can be used to generate code-stubs and documentation.

Its idea is to specify a REST API with a YAML document. This document can be used to generate documentation and methods for API endpoints. While APIs are generally used to decouple software, the OpenAPI spec also allows us to decouple the public interface of our API from our implementation details.

Business and design teams can define the features they need, and an engineering team can create an OpenAPI YAML document that defines all of these in technical terms.

The frontend and backend teams can then use this document as a cornerstone to do their implementation. Both are able to choose their technologies as they see fit.

The OpenAPI ecosystem even provides tools to create mock APIs, so the frontend developers have something more practical to work with.

Why Should We Use It?

There are a bunch of reasons why adding an OpenAPI specification between the frontend and backend can be valuable.

Design First

We can define the whole API with types and examples for every endpoint before we start implementing. With tools that generate mock-APIs, we can verify that everything looks the way we intended. We can refine our API design by simply iterating over the specification document.

Code Generators

OpenAPI is the REST specification which has the most languages supported by code-generators. It generates server stubs in the language of our choice, so that you only have to wire it up with your backend services and databases.

Tooling

The Swagger specification got donated to the OpenAPI foundation and renamed to OpenAPI specification. However, there is a giant ecosystem of tools created under the Swagger brand that can be used to speed up the API development process.

They can be used to generate automatically:

• Documentation
• Tests
• Mock servers

Huge User Base

OpenAPI is used and backed by many large companies. It's seen as the condensed knowledge of building thousands of APIs over the years. This knowledge alone is invaluable if we start out building our first API, but it’s also good to know that there are many people out there to help if something isn’t quite right.

Stable Implementation

As already mentioned, the OpenAPI spec was known as the Swagger spec until 2017, so it's no surprise that it isn’t the first version of the spec. It was at version 3.0 where the rebrand from Swagger to OpenAPI took place.

Currently, the spec doesn’t change too often and, indeed, can be considered mature at this point.

Why We Shouldn't Use It

The OpenAPI specification isn’t a silver bullet that can solve all problems that arise when building an API.

No RESTful API

If we use GraphQL, we don’t need OpenAPI. However, sometimes it isn’t so cut and dry. Sometimes when we need to build an API, we think it'll be RESTful, but when examining the features that are needed, it turns out we will need something that's non-RESTful.

For example, if we want to build a fan event-based system, then perhaps something like gRPC or AsyncAPI may be a better fit.

Added Complexity

As with all tools we add to our projects, there is the risk of added complexity that doesn’t bring any benefits. Many people got burned by SOAP in the past, even if the OpenAPI spec isn’t as massive, it can lead to problems when not used correctly.

We need to find an integration for the framework of our choice, or we need to switch to a framework that supports OpenAPI specifications. Then we could find out that the performance of the other framework isn’t good enough, or it’s not maintained anymore.

Also, every line of code we write is a potential source of errors, even if it's YAML.

The developers building the API also have to acquire the skills to use OpenAPI, and its tools.

Substituting Missing Skills

OpenAPI can be overkill when we've already got senior API devs who know their trade. However, it can also help to be a guide for those less experienced. The problem is, we need to train these people and not just hope OpenAPI will save us from lousy API design choices.

It should be a tool to help people and not a replacement for educating them.

Tools

There is an ample supply of tooling to make using OpenAPI simple. Converters, data-validators, documentation, editors, mock-servers, and generators for testing and SDKs.

Most of it can be found online.

Alternatives?

There are of course many alternatives to the OpenAPI spec. While they have lower adoption rates, it could be that they push all of the right buttons with the developers and are easier to understand and use.

• RAML - The RESTful API Modeling Language RAML is a bit more lightweight than OpenAPI but still based on YAML.
• API Blueprint. A powerful high-level API description language for web APIs. API Blueprint uses its own (non-YAML) syntax.

Conclusion

OpenAPI is one of may attempts of casting decades of API building skills into a specification. Seemingly even the one with the most mind-share and money behind it.

The OpenAPI Initiative is part of the Linux Foundation, which makes it more trustworthy and likely to remain supported.

It isn’t a silver bullet and probably isn't for everyone, but if used right, the added complexity can save quite a bit time in documentation writing, testing and validation.