| OpenAPI | |
| Long Name: | OpenAPI Specification |
| Version: | 3.1.0 |
The OpenAPI Specification, previously known as the Swagger Specification, is a specification for a machine-readable interface definition language for describing, producing, consuming and visualizing web services.[1] Previously part of the Swagger framework, it became a separate project in 2015, overseen by the OpenAPI Initiative, an open-source collaboration project of the Linux Foundation.[2]
An OpenAPI document represents a formal description of an API that tools can use to generate code, documentation, test cases, and more.
Swagger development began in early 2010 by Tony Tam, who was working at online dictionary company Wordnik.[3]
In March 2015, SmartBear Software acquired the open-source Swagger API specification from Reverb Technologies, Wordnik's parent company.[4]
In November 2015, SmartBear announced that it was donating the Swagger specification to a new organization called the OpenAPI Initiative, under the sponsorship of the Linux Foundation. Other founding member companies included 3scale, Apigee, Capital One, Google, IBM, Intuit, Microsoft, PayPal, and Restlet.[5] [6]
On 1 January 2016, the Swagger specification was renamed the OpenAPI Specification (OAS) and was moved to a new GitHub repository.[7]
In July 2017, the OpenAPI Initiative released version 3.0.0 of its specification.[8] MuleSoft, the main contributor to the alternative RESTful API Modeling Language (RAML), joined the OAS and open-sourced its API Modeling Framework tool, which can generate OAS documents from RAML input.[9]
In February 2021, the OpenAPI Initiative released version 3.1.0.[10] Major changes in OpenAPI Specification 3.1.0 include JSON schema vocabularies alignment, new top-level elements for describing webhooks that are registered and managed out of band, support for identifying API licenses using the standard SPDX identifier, allowance of descriptions alongside the use of schema references and a change to make the PathItems object optional to simplify creation of reusable libraries of components.[11] [12] [13]
| Version | Date | Notes[14] | |
|---|---|---|---|
| 3.1.0 | 2021-02-15 | Release of the OpenAPI Specification 3.1.0 | |
| 3.0.3 | 2020-02-20 | Patch release of the OpenAPI Specification 3.0.3 | |
| 3.0.2 | 2018-10-08 | Patch release of the OpenAPI Specification 3.0.2 | |
| 3.0.1 | 2017-12-06 | Patch release of the OpenAPI Specification 3.0.1 | |
| 3.0.0 | 2017-07-26 | Release of the OpenAPI Specification 3.0.0 | |
| 2.0 | 2014-09-08 | Release of Swagger 2.0 | |
| 1.2 | 2014-03-14 | Initial release of the formal document | |
| 1.1 | 2012-08-22 | Release of Swagger 1.1 | |
| 1.0 | 2011-08-10 | First release of the Swagger Specification |
Applications implemented based on OpenAPI interface files can automatically generate documentation of methods, parameters and data models. This helps keep the documentation, client libraries and source code in sync.[15]
When an OpenAPI document is used to generate source code stubs for servers, the process is called scaffolding.
The paradigm of agreeing on an API contract first and then programming business logic afterwards, in contrast to coding the program first and then writing a retrospective description of its behavior as the contract, is called contract-first development. Since the interface is determined before any code is written, downstream developers can mock the server behavior and start testing right away.[16] In this sense, contract-first development is also a practice of shift-left testing.
The OpenAPI Specification is language-agnostic. With OpenAPI's declarative resource specification, clients can understand and consume services without knowledge of server implementation or access to the server code.
The OpenAPI Initiative maintains a list of implementations for version 3.0 of the specification. SmartBear still brands its OpenAPI tools with the Swagger moniker. The Swagger UI framework allows both developers and non-developers to interact with the API in a sandbox UI that gives insight into how the API responds to parameters and options. Swagger can handle both JSON and XML.
Swagger Codegen contains a template-driven engine to generate documentation, API clients and server stubs in different languages by parsing the OpenAPI definition. In July, 2018, William Cheng, the top contributor to Swagger Codegen, and over 40 other contributors to Swagger Codegen forked the code into a project named OpenAPI Generator under the OpenAPI Tools organization.[17] [18]
The OpenAPI Initiative sponsors an annual API Specifications Conference (ASC). The event has its origins in the API Strategy and Practice Conference (APIStrat) that ran for many years and became part of the OpenAPI Initiative in 2016.