OpenAPI Specification

The OpenAPI Specification (OAS), previously known as the Swagger Specification, is a specification for a machine-readable interface definition language for describing, producing, consuming and visualizing web services.

Uses your system voice; voice and rate in settings.

≈ 4 min read

Cite, export and learn8 citation formats · 8 exports · lesson and quiz

Names in other languages

No names in other languages are held for this entry yet.

Article bodies are English and are not machine-translated. A name in another language is not a translation of the article.

The OpenAPI Specification (OAS), previously known as the Swagger Specification, is a specification for a machine-readable interface definition language for describing, producing, consuming and visualizing web services. 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.

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 Linux Foundation. Other founding member companies included 3scale, Apigee, Capital One, Google, IBM, Intuit, Microsoft, PayPal, and Restlet.

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

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.

Version History

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. In September 2025, the OpenAPI Initiative released version 3.2.0 of the OAS.

Notable features include structured tags, first-class streaming media type support, support for arbitrary HTTP methods, clearer example semantics for serializations, OAuth2 device flow and metadata enhancements, and clarified path templating and routing semantics.

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 models. This helps keep the documentation, client libraries and source code in sync. When an OAD is used to generate source code stubs for servers, the process is called scaffolding.

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 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 resource specification, clients can understand and consume services without knowledge of server implementation or access to the server code.

Conferences and conference tracks

The OpenAPI Initiative sponsored APIStrat from 2017 to 2019, converting it into the API Specifications Confererence (ASC) from 2020 to 2022. Starting in 2023, the initiative has instead sponsored OpenAPI tracks at multiple conferences throughout the year.

See also

Representational state transfer gRPC Data modelling

OpenAPI Initiative (OAI) main website OAI Specifications website OAI Learn OpenAPI website OAI Tools website OpenAPI Specification on GitHub Directory of OpenAPI Descriptions

Text derived from https://en.wikipedia.org/w/index.php?oldid=1359525921 under CC BY-SA 4.0; modifications have been made.

Words in each sectionVersion HistoryVersion HistoryVersion History: 135 words135HistoryHistoryHistory: 100 words100Relationships to softwa…Relationships to software engineering practicesRelationships to software engineering practices: 72 words72UsageUsageUsage: 64 words64Consolidation of FormatsConsolidation of FormatsConsolidation of Formats: 58 words58Conferences and confere…Conferences and conference tracksConferences and conference tracks: 37 words37FeaturesFeaturesFeatures: 29 words29See alsoSee alsoSee also: 6 words6
Words in each section. Measured from the stored article body; sections below the minimum are not plotted.

Provenance

snapshot enwiki-001359525921 · captured 2026-06-15 · ledger · version history

Cite this page as: encyclopegia.org, “OpenAPI Specification”, snapshot enwiki-001359525921. https://encyclopegia.org/a/openapi-specification

Sources cited in this revision

23 named source(s) extracted from the cited revision. A source with no author is shown by its publication; nothing is invented.