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
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 describe an inter ...
for describing, producing, consuming and visualizing
REST
Rest or REST may refer to:
Relief from activity
* Sleep
** Bed rest
* Kneeling
* Lying (position)
* Sitting
* Squatting position
Structural support
* Structural support
** Rest (cue sports)
** Armrest
** Headrest
** Footrest
Arts and entert ...
ful
web services. Previously part of the
Swagger framework, it became a separate project in 2016, overseen by the OpenAPI Initiative, an open-source collaboration project of the
Linux Foundation
The Linux Foundation (LF) is a non-profit technology consortium founded in 2000 as a merger between Open Source Development Labs and the Free Standards Group to standardize Linux, support its growth, and promote its commercial adoption. Additi ...
.
Swagger and some other tools can generate code, documentation and test cases from interface files.
History
Swagger development began in early 2010 by Tony Tam, who was working at online dictionary company
Wordnik
Wordnik, a nonprofit organization, is an online English dictionary and language resource that provides dictionary and thesaurus content. Some of the content is based on print dictionaries such as the ''Century Dictionary'', the ''American Heritage ...
.
In March 2015,
SmartBear Software
SmartBear Software is an American privately-held information technology company that delivers tools for application performance monitoring (APM), software development, software testing, API testing and API management. The company is based in ...
acquired the open-source Swagger API specification from Reverb Technologies, Wordnik's parent company.
In November 2015, SmartBear announced that it was creating a new organization called the OpenAPI Initiative under the sponsorship of the
Linux Foundation
The Linux Foundation (LF) is a non-profit technology consortium founded in 2000 as a merger between Open Source Development Labs and the Free Standards Group to standardize Linux, support its growth, and promote its commercial adoption. Additi ...
. Other founding member companies included
3scale,
Apigee
Apigee Corp. was an API management and predictive analytics software provider before its merger into Google Cloud. It was founded in 2004 as Sonoa Systems before being rebranded as Apigee in 2010. Apigee was acquired by Google in a deal worth ...
,
Capital One
Capital One Financial Corporation is an American bank holding company specializing in credit cards, auto loans, banking, and savings accounts, headquartered in McLean, Virginia with operations primarily in the United States. It is on the list o ...
,
Google
Google LLC () is an American multinational technology company focusing on search engine technology, online advertising, cloud computing, computer software, quantum computing, e-commerce, artificial intelligence, and consumer electronics. ...
,
IBM,
Intuit
Intuit Inc. is an American 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 preparation application Tu ...
,
Microsoft
Microsoft Corporation is an American multinational technology corporation producing computer software, consumer electronics, personal computers, and related services headquartered at the Microsoft Redmond campus located in Redmond, Washing ...
,
PayPal
PayPal Holdings, Inc. is an American multinational financial technology company operating an online payments system in the majority of countries that support online money transfers, and serves as an electronic alternative to traditional paper ...
, and Restlet.
SmartBear donated the Swagger specification to the new group.
RAML an
API Blueprintwere also under consideration by the group.
On 1 January 2016, the Swagger specification was renamed the OpenAPI Specification (OAS) and was moved to a new
GitHub
GitHub, Inc. () is an Internet hosting service for software development and version control using Git. It provides the distributed version control of Git plus access control, bug tracking, software feature requests, task management, continuous ...
repository
Repository may refer to:
Archives and online databases
* Content repository, a database with an associated set of data management tools, allowing application-independent access to the content
* Disciplinary repository (or subject repository), an ...
.
In September 2016, the API World conference presented an API Infrastructure award to SmartBear for its ongoing work on Swagger.
In July 2017, the OpenAPI Initiative released version 3.0.0 of its specification.
MuleSoft
MuleSoft, LLC. is a software company headquartered in San Francisco, California, that provides integration software for connecting applications, data and devices. Started in 2006, the company's Anypoint Platform of integration products is designe ...
, the main contributor to the alternative
RESTful API Modeling Language
RESTful API Modeling Language (RAML) is a YAML-based language for describing static APIs (but not REST APIs). It provides all the information necessary to describe APIs on the level 2 of the Richardson Maturity Model. Although designed with RE ...
(RAML), joined the OAS and open-sourced its API Modeling Framework tool, which can generate OAS documents from RAML input.
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 in order to simplify creation of reusable libraries of components.
Release dates
Usage
Applications implemented based on OpenAPI interface files can automatically generate documentation of methods, parameters and models. 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 manageme ...
, client libraries and source code in sync.
When an OpenAPI document is used to generate source code, 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 man-made structures. Scaffolds are widely use ...
.
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 an 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 functionality for other programs or devices, called clients
Role
* Waiting staff, those who work at a restaurant or a bar attending customers and su ...
behavior and start testing right away. In this sense, contract-first development is also a practice of
shift-left testing
Shift-left testing is an approach to software testing and system testing in which testing is performed earlier in the lifecycle (i.e. moved left on the project timeline). It is the first half of the maxim "test early and often". It was coined by ...
.
Features
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.
Tools that work with OpenAPI
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
JSON (JavaScript Object Notation, pronounced ; also ) is an open standard file format and data interchange format that uses human-readable text to store and transmit data objects consisting of attribute–value pairs and arrays (or other ser ...
and
XML
Extensible Markup Language (XML) is a markup language and file format for storing, transmitting, and reconstructing arbitrary data. It defines a set of rules for encoding documents in a format that is both human-readable and machine-readable. T ...
.
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 name
OpenAPI Generatorunder the OpenAPI Tools organization.
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.
See also
*
Representational State Transfer
*
Overview of RESTful API Description Languages RESTful (representational state transfer) API (application programming interface) DLs (description languages) are formal languages designed to provide a structured description of a RESTful web API that is useful both to a human and for automated mac ...
including RAML, WADL, WSDL, and others.
*
gRPC
gRPC (Google Remote Procedure Calls) is a cross-platform open source high performance Remote Procedure Call (RPC) framework. gRPC was initially created by Google, which has used a single general-purpose RPC infrastructure called Stubby to conne ...
References
Bibliography
*
*
External links
OpenAPI Initiative (OAI) websiteAPI Specifications Conference (ASC) websiteSwagger websiteOpenAPI Specification on GitHubDirectory of OpenAPI definitions OpenAPI Editor: A rich UI Eclipse OpenAPI (OAS) editor and studio to design, develop and test OAS3/OpenAPI_OpenAPI_for_Electronic_data_interchange_(EDI).html" ;"title="Electronic data interchange"> OpenAPI for
Electronic_data_interchange">_OpenAPI_for_Electronic_data_interchange_(EDI)
{{Use_dmy_dates.html" ;"title="Electronic data interchange
(EDI)">Electronic data interchange"> OpenAPI for Electronic data interchange
(EDI)
{{Use dmy dates">date=April 2019
Software architecture