HOME

TheInfoList



OR:

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 specificat ...
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 ente ...
ful web services. Previously part of the
Swagger A swagger or swagga is a swaggering gait. Swagger also may refer to: * Swagger or swagman, a transient labourer in Australia and New Zealand * Swagger (software), a specification for defining the interface of a REST web service now known as Ope ...
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. Addi ...
. Swagger and some other tools can generate code, documentation and test cases from interface files.


History

Swagger A swagger or swagga is a swaggering gait. Swagger also may refer to: * Swagger or swagman, a transient labourer in Australia and New Zealand * Swagger (software), a specification for defining the interface of a REST web service now known as Ope ...
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 Heritag ...
. 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 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. Addi ...
. Other founding member companies included
3scale 3scale is an internet technology company that develops API management software. History 3scale was co-founded by Steven Willmott and Martin Tantow in 2007. A public beta began in November 2008. The company's commercial product was released in M ...
, Apigee,
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 ...
,
Google Google LLC () is an American Multinational corporation, multinational technology company focusing on Search Engine, search engine technology, online advertising, cloud computing, software, computer software, quantum computing, e-commerce, ar ...
, 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 corporation, multinational technology company, technology corporation producing Software, computer software, consumer electronics, personal computers, and related services headquartered at th ...
,
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 Blueprint
were 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, co ...
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), a ...
. 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 R ...
(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 Mock is an imitation, usually of lesser quality Mock may refer to: Names * Mock (surname) *Mock, or Duncan Stump, a member of the band Mock & Toof *Mock, a character in the Japanese anime series '' Mock & Sweet'' Places *Mock, Washington, a gho ...
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 s ...
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. ...
. 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 Generator
under 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 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) website

API Specifications Conference (ASC) website

Swagger website

OpenAPI Specification on GitHub

Directory 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)">Electronic data interchange"> OpenAPI for Electronic data interchange
(EDI) {{Use dmy dates">date=April 2019 Software architecture