A brief history of the OpenAPI Specification

In 2009, Tony Tam of Wordnik (an online dictionary service) had begun working on what would become the Swagger Specification. Used to describe Wordnik's JSON API, Swagger was used to drive Wordnik's developer console / documentation (which can still be seen at https://developer.wordnik.com/docs), their server integration and code-generation within the company.

Initially known as SWAGR - "why WADL, when you can SWAGR?" said Wordnik colleague Zeke Sikelianos when discussing potential names for the project with Tam (though if SWAGR ever stood for anything, it appears to be lost in the mists of time) - Tam published the first version of the Swagger Specification (1.0) in August 2011, just one month after Mashery announced I/O Docs, though there had been at least a 0.1a version used internally.

While working at Reverb Technologies, Tam published version 1.1 of the Swagger Specification in August 2012. This was a minor refinement of the specification only.

Version 1.2 of the Swagger Specification was the first version written up as a formal specification document, in March 2014, separating the specification itself from the Swagger implementation. Improvements were made to the type system, to bring it more into line with JSON Schema Draft 4. This was the first version to gain widespread adoption across the API industry, and is still in use by some API providers today.

September 2014 saw the release of the Swagger Specification 2.0. This saw a reorganisation from the two-file format of Swagger 1.2 and earlier into a single document structure, but one that could still reference sub-documents using the JSON-Reference standard. Further improvements were made to the type system / JSON Schema support, fuller API metadata support with the contact and license objects, the use of markdown in descriptions was allowed and vendor extensions (now known as specification extensions) and response headers were supported among other more minor changes. Swagger 2.0 saw more growth and adoption across the industry, and the number of supporting commercial solutions and open-source offerings increased dramatically.

In March 2015, SmartBear Software, a leading API testing and development tool company, acquired the interests in the Swagger intellectual property and open-source projects from Reverb Technologies.

In September 2015, Tam joined SmartBear Software as VP of Products, Swagger.

In December 2015, the Swagger Specification was donated by SmartBear Software to a new open-governance organisation, set up under the auspices of the Linux Foundation: the OpenAPI Initiative (https://openapis.org).

Version 2.0 of the OpenAPI Specification (as it was now known) was identical to the Swagger 2.0 specification. Although there was, and remains, some confusion between the use of the terms Swagger and OpenAPI, this was a positive first step in the transition to the new governance body and the new name for the specification.

Ten companies were founding members of the OpenAPI Initiative (3Scale, Apigee, CapitalOne, Google, IBM, Intuit, Microsoft, PayPal, Restlet and SmartBear) and the number of member organisations now stands at over 30.

The OpenAPI Specification is now managed by a Technical Steering Committee (TSC), and since the departure of Tony Tam in 2017 this has comprised long-time contributor Ron Ratovsky of SmartBear Software, Darrel Miller of Microsoft, Jeremy Whitlock and Marsh Gardiner, both now at Google, Uri Sarid of Mulesoft, and the author of this blog. The TSC draw from the wider Technical Developer Community to develop the specification in an open, transparent fashion. Membership of the OAI does not confer voting rights over content of the specification itself.

In July 2017, the OpenAPI Initiative announced the release of version 3.0.0 of the OpenAPI Specification, containing several structural improvements, closer alignment with JSON Schema draft 5, new features such as links and callbacks, standardisation on CommonMark for descriptions and many small tweaks and clarifications. Two patch releases to the 3.0 line were made in 2018. Version 3.1.0 of the specification is being actively worked on, and a release is expected in mid 2019.

The OpenAPI Initiative defines the OpenAPI Specification in these terms:

"The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for REST APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service."

Just as REST is not the new SOAP, OpenAPI is not the new WSDL. Its capacity for design-first development, wide range of tooling and cross-platform support take it to places only dreamed of by web services.

Like any API description language, the OpenAPI Specification is not capable of fully describing every conceivable API design, so retrofitting it to an existing code-base can be an uphill struggle. But as you gain familiarity with the OAS and adopt or transition to a design-first workflow, you will begin to see patterns emerge in the specification which will help shape your design decisions. Not only will you be working with the specification and not against it, you will gain commonality with other APIs described using the OAS, which will translate into familiarity and clear understanding by users of your API who also understand the OAS and perhaps have experience of many other APIs described with it.

The OpenAPI Specification has a rich ecosystem of tooling, both commercial and open-source (where more than 2,000 projects are known to exist, though not all of them yet have support for OpenAPI 3.0). This ranges from editors and low-level parsers and validators, to documentation-generators and dynamic consoles, testing tools and code-generation services.

Thanks to Tony Tam for providing a correction to this article.