OpenAPI Specification

From HandWiki
Short description: A specification for machine-readable interface files
OpenAPI
OpenAPI Specification
Year started2010 (2010)
First published10 August 2011 (2011-08-10)
Latest version3.2.0
19 September 2025 (2025-09-19)
Websiteopenapis.org

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] 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.[2][3]

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

History

Logo of the OpenAPI Initiative, the organization that develops the OpenAPI specification under the Linux Foundation

Swagger development began in early 2010 by Tony Tam, who was working at online dictionary company Wordnik.[5]

In March 2015, SmartBear Software acquired the open-source Swagger API specification from Reverb Technologies, Wordnik's parent company.[6]

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.[7][8]

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

In July 2017, the OpenAPI Initiative released version 3.0.0 of its specification.[10]

In February 2021, the OpenAPI Initiative released version 3.1.0.[11] 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.[12][13][14]

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[15] and MuleSoft in 2017.[16] Both have added support for the OAS.[17][16]

Release dates

Version Date Notes[18]
3.2.0 2025-09-19 Release of the OpenAPI Specification 3.2.0
3.1.2 2025-09-19 Patch release of the OpenAPI Specification 3.1.2
3.1.1 2024-10-24 Patch release of the OpenAPI Specification 3.1.1
3.1.0 2021-02-15 Release of the OpenAPI Specification 3.1.0
3.0.4 2024-10-24 Patch release of the OpenAPI Specification 3.0.4
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

Usage

The OAS describes the format for OpenAPI Descriptions (OADs),[4] 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.[19]

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.[20] 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.[1]

Tools that work with OpenAPI

The OpenAPI Initiative maintains a list of implementations.[21]

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

References

  1. ↑ 1.0 1.1 "OpenAPI Documentation: Getting Started". The OpenAPI Initiative. https://learn.openapis.org/. 
  2. ↑ "New Collaborative Project to Extend Swagger Specification for Building Connected Applications and Services". https://www.linuxfoundation.org/press/press-release/new-collaborative-project-to-extend-swagger-specification-for-building-connected-applications-and-services. 
  3. ↑ "OpenAPI Initiative Charter". https://www.openapis.org/participate/how-to-contribute/governance. 
  4. ↑ 4.0 4.1 "OpenAPI Documentation: Glossary". The OpenAPI Initiative. 2023. https://learn.openapis.org/glossary.html. 
  5. ↑ "Swagger creator joins SmartBear". 28 September 2015. https://sdtimes.com/apis/swagger-creator-joins-smartbear/. 
  6. ↑ "SmartBear Assumes Sponsorship of Swagger API Open Source Project". https://smartbear.com/news/news-releases/sponsorship-of-swagger/. 
  7. ↑ "FAQ". https://www.openapis.org/faq#OAIFAQ-History. 
  8. ↑ "New Collaborative Project to Extend Swagger Specification for Building Connected Applications and Services". http://www.linuxfoundation.org/news-media/announcements/2015/11/new-collaborative-project-extend-swagger-specification-building. 
  9. ↑ OpenAPI Initiative. "OpenAPI Specification". https://github.com/OAI/OpenAPI-Specification. 
  10. ↑ "The OAI Announces the OpenAPI Specification 3.0.0". July 26, 2017. https://www.openapis.org/blog/2017/07/26/the-oai-announces-the-openapi-specification-3-0-0. 
  11. ↑ "OpenAPI Specification 3.1.0 Available Now". April 26, 2021. https://www.linux.com/news/openapi-specification-3-1-0-available-now. 
  12. ↑ Charboneau, Tyler (April 7, 2021). "What's New in OpenAPI 3.1.0?". https://nordicapis.com/whats-new-in-openapi-3-1-0/. 
  13. ↑ "OpenAPI Specification 3.1.0 Released". February 18, 2021. https://www.openapis.org/blog/2021/02/18/openapi-specification-3-1-released. 
  14. ↑ Sturgeon, Phil (February 16, 2021). "Migrating from OpenAPI 3.0 to 3.1.0". https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0. 
  15. ↑ Lensmar, Ole (23 February 2016). "OAI Update – new members, OpenAPI Spec 3.0 progress, and more!". https://www.openapis.org/blog/2016/02/23/oai-update-new-members-openapi-spec-3-0-progress-and-more. Retrieved 13 October 2024. 
  16. ↑ 16.0 16.1 Avram, Abel (May 6, 2017). "The HTTP API space is Consolidating around OAS". https://www.infoq.com/news/2017/05/api-raml-oas. 
  17. ↑ Nesetril, Jakub (18 January 2016). "We've got Swagger". https://blog.apiary.io/We-ve-got-Swagger. Retrieved 13 October 2024. 
  18. ↑ "OpenAPI Specification Version 3.2.0". https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.2.0.md. 
  19. ↑ "OpenAPI Documentation: Introduction". The OpenAPI Initiative. 2023. https://learn.openapis.org/introduction.html. 
  20. ↑ Preibisch, Sascha (2018). API Development: A Practical Guide for Business Implementation Success. [Berkeley, CA]: Apress. ISBN 978-1-4842-4140-0. OCLC 1076234393. "Having the Swagger (or for that matter, any other machine-readable) document available, team members can start working on their part of the project at the same time." 
  21. ↑ "OpenAPI Tooling". The OpenAPI Initiative. https://tools.openapis.org/. 

Bibliography

Template:Linux Foundation



Retrieved from "https://handwiki.org/wiki/index.php?title=OpenAPI_Specification&oldid=4153552"