The OpenAPI Specification is adored, and its usefulness has seen it be subject to sweeping adoption in recent years. It’s clear that many see the value of the OpenAPI Specification, and see value in its adoption.

As with any trend, there’s a certain amount of consideration that should be paid before adopting the solution carte blanche. While many adopters are certainly doing their due diligence, it bears some discussion within the greater scheme of the API industry to address what to expect with OpenAPI before diving in.

To that end, let’s discuss the OpenAPI Specification. We’ll discuss what it is exactly, where it came from, and where it’s going. We’ll look at some pros and cons of adopting the specification, as well as some hints on what to consider before the implementation is undertaken.

What is the OpenAPI Specification?

OpenAPI Specification

OpenAPI Specification can be used to secure and accelerate the API lifecycle.

OpenAPI, known by its more formal name as the OpenAPI Specification, is a specification and initiative for the creation of machine-readable interface files used to describe, produce, consume, and visualize RESTful web services. Alongside the specification, tools like the Swagger toolset exist to generate code, documentation, test cases, and more. Currently, the OpenAPI Specification is curated and overseen by the Open API Initiative.

The progenitor of OpenAPI Specification was the Swagger Specification. Swagger began development in early 2010, and in March 2015, the definition was acquired by SmartBear Software. By November of that year, SmartBear announced the creation of a new organization under the sponsorship of the Linux Foundation called the Open API Initiative. The organization was comprised of some rather large players in the industry including Google, Microsoft and IBM, all focusing on the development of this open concept.

To aid in development, SmartBear donated the Swagger specification, where it was renamed the OpenAPI Specification, and was moved to a new GitHub repository. In 2017, the OpenAPI Specification version 3.0 was released, and MuleSoft, the chief contributor to RESTful API Modeling Language (RAML) joined the OpenAPI Specification committee to allow for the generation of OAS documents from RAML.

With such a storied pedigree, it should be obvious that the OpenAPI Specification is here to stay, and its development seems to be expanding as each new partner joins the OpenAPI Specification organization. The entire focus of Swagger was on streamlining and synchronizing update workflow and allowing for more dynamic server and client code and documentation generation — and for this reason, OpenAPI is very attractive to the average developer.

OpenAPI vs “Open API”

Before we discuss the OpenAPI Specification, we should first differentiate two very common and conflated terms. When discussing this topic, there’s the “OpenAPI Specification” and there’s the concept of an “open API”.

The concept of an open API is that the API should be composed primarily of open source modules, or at the very least, should be open to inspection and utilization. An open API is can be forked, developed into new things, or changed and morphed in a free way. Open source is a noble goal, but there’s a huge difference between that and the idea of the OpenAPI Specification, which is fundamentally a guided interaction and set versioning for development.

As we move forward, this should be a strong consideration — while some more public facing, open APIs may use OpenAPI Specification, OpenAPI is not synonymous with open APIs.

Benefits of Adopting the OpenAPI Specification

So what makes OpenAPI such an attractive proposition? There’s the obvious value that we’ve already discussed, of course — OpenAPI is backed by some huge players in the industry, and as such, represents a mindshare in the industry that is seriously valuable.

Being backed by so many large players also suggests that, over time, the implementation is stable. It’s less likely to be abandoned or merged with other solutions, given how prolific the implementation development has been up until this point. It should also be considered that OpenAPI is an open specification backed by some of the largest proprietary codebase designers — in that way, it has been suggested that OpenAPI will likely provide some sort of co-functionality and interfacing in the future if development continues in the way it has been.

Perhaps the strongest argument for the OpenAPI specification is its background in Swagger. Swagger has existed for so long and has such a large community and support base that, when it was turned into the OpenAPI Specification, it carried over some of the greatest talent and most prolific community members into the new solution. This is much the same with its adoption rate, as Swagger was so widely adopted and considered — due to this, OpenAPI has likewise seen quite wide adoption.

Additionally, building upon the wide language support of Swagger, the OpenAPI Specification considers itself to be language-agnostic. For most developers, this is a godsend.

For a more technical overview of OpenAPI adoption, read: 5 Ways the OpenAPI Specification Spurs API Agility

Potential Drawbacks of OpenAPI Adoption

Of course, with any technology, there are some considerations that should be internalized and considered as part of a broader plan of adoption. For OpenAPI, this may be especially true amongst hypermedia API providers.

First and foremost, the aforementioned language-agnostic quality of OpenAPI is great for inclusivity, but also introduces a good deal of complexity in the incorporation of language-specific frameworks, third party APIs, and server-based extensions. Some solutions are only designed to work within specific languages — and while it could be argued that this is a drawback of said solutions, the fact is that many providers don’t have a choice in the matter. Forcing them to re-address their solutions to implement the specification is a hard sell, especially when the OpenAPI Specification notes that an API won’t have to be rewritten to utilize the specification.

A major issue with the OpenAPI Specification is that, in many ways, it’s simply an additional step to fix what are otherwise major issues in schema-centric design. The OpenAPI Specification creates a great framework for development, but it essentially functions as a shortcut to actual knowledge and understanding. In other words, for developers unfamiliar with its concepts, OpenAPI can function as a bandaid rather than a toolset.

Kin Lane, The API Evangelist, stated it best on his blog:

Folks need to learn about consistent design patterns for their requests and responses. Think about getting their schema house in order. Think through content negotiation in a consistent way. […] For you (the hypermedia guru), OpenAPI is redundant, meaningless, and unnecessary. For many others, it provides them with a healthy blueprint to follow and allows you to be spoon fed web literacy, and good API design practices in the increments your daily job, and current budget allows.

That’s not to say there’s necessarily a problem with OpenAPI itself — but when considering adoption, providers should consider whether the adoption is as a framework for better APIs, or as a bandaid to bridge their lack of understanding about best practices and development.

Even with all of that being said it should also be noted that the OpenAPI Specification itself is not compatible with every single type of API. Some services aren’t describable in the way the Specification behaves. As the documentation on the official website notes:

The OpenAPI Specification does not require rewriting existing APIs. It does not require binding any software to a service — the service being described may not even be owned by the creator of its description. It does, however, require the capabilities of the service be described in the structure of the OpenAPI Specification. Not all services can be described by OpenAPI — this specification is not intended to cover every possible style of REST APIs.

Updates in the OpenAPI World

So where is OpenAPI heading? To see the value of the OpenAPI Specification, we can take a look at some of the most recent OpenAPI news.

A major landmark this year was RepreZen joining the OpenAPI Initiative. RepreZen are the creators of the RAPID-ML resource modeling language, and as such, their addition into the organization means developers now have a great editor to work in OAS with. CEO Ted Epstein summarized his efforts as moving outside of the framework approach that OpenAPI has thus far operated under and more towards full integration:

This is a generic blueprint for the API contract as code, using the Open API specification not just for documentation and not just for a one-time code generation template that gives you some scaffolding code. This is really fully integrating the API spec into your code. When you’re working with the OpenAPI Specification, it’s definitely a higher level of abstraction. For every line of OpenAPI code you write, you get 20 lines of executable code [With RepreZen,] you get this abstraction but you also get full visibility into your code.

The OpenAPI Specification itself saw some major movement in 2017, with the release of version 3.0.0. Adding support for describing callbacks, improving handling for multipart documents, adding the ability to express relationships between operations as links, and more, 3.0.0 marks a major goalpost for the implementation, and suggests some major leaps and bounds are still in the woodwork.

SmartBear Software CTO and OAI Board Chair Ole Lensmar summarized the release as thus in official PR releases:

The release of this third-generation format is a significant milestone for our community. The updates made are entirely user and usage driven and that plays a huge role in the success of the specification. One of the most powerful things about this release is its ability to drive the full API lifecycle.

OpenAPI Specification has seen leaps and bounds in adoption. Lensmar went on to say that its expanded it’s member growth by a factor of 4 in the last 18 months — now including 42Crunch, Adobe, Cloud Elements, Oracle Apiary, Red Hat, Tyk, Intento, and more members along with 20 other partners. It’s usage is also seeping into new sectors, with increasing interest form government and healthcare, FinTech organizations. This massive growth signals that the industry is ready for OpenAPI, and obviously sees the value of such a specification.


Ultimately, the OpenAPI Specification is extremely valuable, and it should be looked at by API providers as a solid choice for the given use case. The implementation should be considered with as much weight as it’s owed — what we’re talking about here is not just a specification, but a fundamental blueprint and framework that is supported by a huge range of big names that is getting wider and bigger every year.

Accordingly, while OpenAPI should be thought of as valuable as it actually is, due diligence should be the first and foremost consideration before all else.

Kristopher Sandoval

About Kristopher Sandoval

Kristopher Sandoval is a web developer, author, and artist based out of Northern California with over six years of experience in Information Technology and Network Administration. He has been writing articles for Nordic APIs since 2015.