The OpenAPI Specification, previously known as the Swagger Specification, is a

specification A specification often refers to a set of documented requirements to be satisfied by a material, design, product, or service. A specification is often a type of technical standard. There are different types of technical or engineering specificati ...

for a machine-readable

interface definition language An interface description language or interface definition language (IDL) is a generic term for a language that lets a program or object written in one language communicate with another program written in an unknown language. IDLs are usually use ...

for describing, producing, consuming and visualizing

web services A web service (WS) is either: * a service offered by an electronic device to another electronic device, communicating with each other via the Internet, or * a server running on a computer device, listening for requests at a particular port over a n ...

. Originally developed to support the Swagger framework, it became a separate project in 2015, overseen by the OpenAPI Initiative, an open-source collaboration project of the

Linux Foundation The Linux Foundation (LF) is a non-profit organization established in 2000 to support Linux development and open-source software projects. Background The Linux Foundation started as Open Source Development Labs in 2000 to standardize and prom ...

. An OpenAPI Description (OAD) represents a formal description of an API that tools can use to generate code, documentation, test cases, and more.

History

Swagger development began in early 2010 by Tony Tam, who was working at online dictionary company Wordnik. In March 2015, SmartBear Software acquired the open-source Swagger API specification from Reverb Technologies, Wordnik's parent company. 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

. Other founding member companies included 3scale, Apigee,

Capital One Capital One Financial Corporation is an American bank holding company founded on July 21, 1994, and specializing in credit cards, auto loans, banking, and savings accounts, headquartered in Tysons, Virginia, with operations primarily in the ...

Google Google LLC (, ) is an American multinational corporation and technology company focusing on online advertising, search engine technology, cloud computing, computer software, quantum computing, e-commerce, consumer electronics, and artificial ...

IBM International Business Machines Corporation (using the trademark IBM), nicknamed Big Blue, is an American Multinational corporation, multinational technology company headquartered in Armonk, New York, and present in over 175 countries. It is ...

Intuit Intuit Inc. is an American multinational business software company that specializes in financial software. The company is headquartered in Mountain View, California, and the CEO is Sasan Goodarzi. Intuit's products include the tax preparati ...

Microsoft Microsoft Corporation is an American multinational corporation and technology company, technology conglomerate headquartered in Redmond, Washington. Founded in 1975, the company became influential in the History of personal computers#The ear ...

PayPal PayPal Holdings, Inc. is an American multinational financial technology company operating an online payments system in the majority of countries that support E-commerce payment system, online money transfers; it serves as an electronic alter ...

, and Restlet. On 1 January 2016, the Swagger specification was renamed the OpenAPI Specification (OAS) and was moved to a new

GitHub GitHub () is a Proprietary software, proprietary developer platform that allows developers to create, store, manage, and share their code. It uses Git to provide distributed version control and GitHub itself provides access control, bug trackin ...

repository. In July 2017, the OpenAPI Initiative released version 3.0.0 of its specification. In February 2021, the OpenAPI Initiative released version 3.1.0. 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.

Consolidation of Formats

Two somewhat similar technologies, MuleSoft's RESTful API Modeling Language (RAML) and Apiary's API Blueprint, had been developed around the same time as what was then still called the Swagger Specification. The producers of both formats later joined the OpenAPI Initiative: Apiary in 2016 and MuleSoft in 2017. Both have added support for the OAS.

Release dates

Usage

The OAS describes the format for OpenAPI Descriptions (OADs), which can be used by a variety of applications, libraries, and tools. Applications can use OADs to automatically generate documentation of methods, parameters and

data model A data model is an abstract model that organizes elements of data and standardizes how they relate to one another and to the properties of real-world entities. For instance, a data model may specify that the data element representing a car be ...

s. This helps keep the

documentation Documentation is any communicable material that is used to describe, explain or instruct regarding some attributes of an object, system or procedure, such as its parts, assembly, installation, maintenance, and use. As a form of knowledge managem ...

, client libraries and source code in sync. When an OAD is used to generate source code stubs for servers, the process is called

scaffolding Scaffolding, also called scaffold or staging, is a temporary structure used to support a work crew and materials to aid in the construction, maintenance and repair of buildings, bridges and all other human-made structures. Scaffolds are widely u ...

Relationships to software engineering practices

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 Server may refer to: Computing *Server (computing), a computer program or a device that provides requested information for other programs or devices, called clients. Role * Waiting staff, those who work at a restaurant or a bar attending custome ...

behavior and start testing right away. In this sense, contract-first development is also a practice of shift-left testing.

Features

The OpenAPI Specification is language-agnostic. With OpenAPI's

declarative Declarative may refer to: * Declarative learning, acquiring information that one can speak about * Declarative memory, one of two types of long term human memory * Declarative programming, a computer programming paradigm * Declarative sentence, a t ...

resource specification, clients can understand and consume services without knowledge of server implementation or access to the server code.

Tools that work with OpenAPI

The OpenAPI Initiative maintains a list of implementations for version 3.0 of the specification.

Annual conference

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.

References

Bibliography

* *

External links

OpenAPI Initiative (OAI) website

API Specifications Conference (ASC) website

OpenAPI Specification on GitHub

Directory of OpenAPI Descriptions

Example OpenAPI Descriptions on the OAI's official Learn OpenAPIs site
{{Linux Foundation Software architecture Application programming interfaces Markup languages JSON