January 15, 2022 API Product Management

Benefits of using the OpenAPI (Swagger) specification for your API?

With software products being more and more just a bunch of micro-services and third-party APIs mashed together, it gets more crucial for us to get their structure in order.

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

One of the best known is the OpenAPI spec or short OAS.

Enter OpenAPI

The OpenAPI specification was known as Swagger until version 3.0 got released in 2017 and 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 these in technical terms.

as a corner-stone to do their implementation. Both 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 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 it. 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 with the most languages supported by their code-generators. It generates server stubs in the language of our choice, and we have to wire it up with our 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 Userbase

OpenAPI is used and backed by many big companies and can be seen as their 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 bright.

Stable Implementation

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

The spec doesn’t change too often now and can be considered mature at this point.

Why we should not 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 obvious. Sometimes we get the task to build an API, think it will be RESTful, but when learning about the features that are needed, we are better off with something non-RESTful.

If we build, for example, an event-based system, something like gRPC or AsyncAPI may be a better fit for it.

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 some 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 is YAML.

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

Substituting Missing Skills

OpenAPI can be overkill when we already got senior API devs who know their trade, but it can help to be a guideline for less experienced devs. 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 work with OpenAPI even simpler. Converters, data-validators, documentation, editors, mock-servers, and generators for tests and SDKs.

Most of it can be found here: https://openapi.tools/.

Alternatives?

There are, of course, many alternatives to the OpenAPI spec, while they have lower adoption rate, it could be that they are pushing just the right buttons of our 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 a bit more trustworthy and at least look like it won’t go away soon.

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

Make Your API Platform Successful with Moesif 14 day free trial. No credit card required. Learn More

OpenAPI , Swagger

Kay Ploesser

Software Engineer and Web Enthusiast

API Strategy

Announcing General Availability of the Moesif Developer Portal

We’re thrilled to announce the General Availability of the Moesif Developer Portal, a major leap forward enabling you to deploy a seamless experience for dev...

December 06, 2024

API Analytics and Monitoring

Introducing AI Explain

We are thrilled to introduce our newest feature to Moesif - AI Explain - a powerful conversational tool that lets you interact with your API analytics data l...

November 14, 2024