OpenAPI Specification: Difference between revisions

Revision as of 00:07, 18 September 2024

Latest revision as of 19:07, 11 August 2025

(10 intermediate revisions by 6 users not shown)

Line 3:

| title = OpenAPI

| long_name = OpenAPI Specification

| image = OpenAPI Specification Logo Pantone.svg

| image_size =

| alt =

Line 13:

| year_started = {{Start date|2010}}

| first_published = {{Start date|2011|08|10|df=y}}

| version = 3.1.01

| version_date = {{Start date|20212024|0210|1524|df=y}}

| preview =

| preview_date =

Line 28:

| website = {{URL|https://openapis.org}}

}}

The '''OpenAPI Specification''', previously known as the '''Swagger Specification''', is a [[Specification (technical standard)|specification]] for a [[Machine-readable medium|machine-readable]] [[interface definition language]] for describing, producing, consuming and visualizing [[Web API|web services]].<ref name=started>{{cite web |title=OpenAPI Documentation: Getting Started |website=Learn OpenAPI |url=https://learn.openapis.org/ |publisher=The OpenAPI Initiative |access-date=2024-09-17}}</ref> Originally developed to support the [[Swagger (software)|Swagger]] framework, it became a separate project in 2015, overseen by the OpenAPI Initiative, an open-source collaboration project of the [[Linux Foundation]].<ref>{{Cite web|url=https://www.linuxfoundation.org/press/press-release/new-collaborative-project-to-extend-swagger-specification-for-building-connected-applications-and-services|title=New Collaborative Project to Extend Swagger Specification for Building Connected Applications and Services|archive-url=https://web.archive.org/web/20231031170437/https://www.linuxfoundation.org/press/press-release/new-collaborative-project-to-extend-swagger-specification-for-building-connected-applications-and-services|archive-date=31 October 2023}}</ref> Previously part of the [[Swagger (software)|Swagger]] framework, it became a separate project in 2015, overseen by the OpenAPI Initiative, an open-source collaboration project of the [[Linux Foundation]].<ref name="charter">{{cite web |title=OpenAPI Initiative Charter |url=https://www.openapis.org/participate/how-to-contribute/governance |website=OpenAPI Initiative |access-date=12 November 2019 |archive-date=26 January 2025 |archive-url=https://web.archive.org/web/20250126133749/https://www.openapis.org/participate/how-to-contribute/governance |url-status=dead }}</ref>

An OpenAPI documentDescription (OAD)<ref name=glossary>{{cite web|title=OpenAPI Documentation: Glossary |website=Learn OpenAPI |url=https://learn.openapis.org/glossary.html |publisher=The OpenAPI Initiative |date=2023 |access-date=2024-09-17}}</ref> represents a formal description of an API that tools can use to generate code, documentation, test cases, and more.

==History==

[[File:OpenAPI Logo Pantone.svg|thumb|Logo of the OpenAPI Initiative, the organization that develops the OpenAPI specification under the [[Linux Foundation]]]]

[[Swagger (software)|Swagger]] development began in early 2010 by Tony Tam, who was working at online dictionary company [[Wordnik]].<ref>{{cite web|url=https://sdtimes.com/apis/swagger-creator-joins-smartbear/|title=Swagger creator joins SmartBear|date=28 September 2015 |access-date=August 6, 2019}}</ref>

In March 2015, [[SmartBear Software]] acquired the open-source Swagger API specification from Reverb Technologies, Wordnik's parent company.<ref>{{Cite web|title = SmartBear Assumes Sponsorship of Swagger API Open Source Project|url=https://smartbear.com/news/news-releases/sponsorship-of-swagger/|website = SmartBear|access-date = 2015-03-25}}</ref>

Line 41 ⟶ 42:

On 1 January 2016, the Swagger specification was renamed the OpenAPI Specification (OAS) and was moved to a new [[GitHub]] [[Software repository|repository]].<ref>{{cite web |last1=OpenAPI Initiative |title=OpenAPI Specification |url=https://github.com/OAI/OpenAPI-Specification |website=GitHub |access-date=12 November 2019}}</ref>

In July 2017, the OpenAPI Initiative released version 3.0.0 of its specification.<ref>{{Cite web|url=https://www.openapis.org/blog/2017/07/26/the-oai-announces-the-openapi-specification-3-0-0 |date=July 26, 2017 |title=The OAI Announces the OpenAPI Specification 3.0.0|website=OpenAPIs|access-date=2018-04-19}}</ref> [[MuleSoft]], the main contributor to the alternative [[RESTful API Modeling Language]] (RAML), joined the OAS and open-sourced its API Modeling Framework tool, which can generate OAS documents from RAML input.<ref>{{Cite web|url=https://www.infoq.com/news/2017/05/api-raml-oas |first1=Abel |last1=Avram |date=May 6, 2017 |title=The HTTP API space is Consolidating around OAS|website=InfoQ|access-date=2017-05-14}}</ref>

In February 2021, the OpenAPI Initiative released version 3.1.0.<ref>{{Cite web|url=https://www.linux.com/news/openapi-specification-3-1-0-available-now |date=April 26, 2021 |title=OpenAPI Specification 3.1.0 Available Now|website=Linux.com|access-date=2021-04-26}}</ref> 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.<ref>{{Cite web|url=https://nordicapis.com/whats-new-in-openapi-3-1-0/ |first1=Tyler |last1=Charboneau |date=April 7, 2021 |title=What's New in OpenAPI 3.1.0?|website=Nordic APIs|access-date=2021-04-07}}</ref><ref>{{Cite web|url=https://www.openapis.org/blog/2021/02/18/openapi-specification-3-1-released |date=February 18, 2021 |title=OpenAPI Specification 3.1.0 Released|website=OpenAPI Initiative|access-date=2021-02-18}}</ref><ref>{{Cite web|url=https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0 |first1=Phil |last1=Sturgeon |date=February 16, 2021 |title=Migrating from OpenAPI 3.0 to 3.1.0|website=OpenAPI Initiative|access-date=2021-02-16}}</ref>

===Consolidation of Formats===

==Release dates==

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<ref>{{cite web|url=https://www.openapis.org/blog/2016/02/23/oai-update-new-members-openapi-spec-3-0-progress-and-more |website=The OpenAPI Initiative|title=OAI Update – new members, OpenAPI Spec 3.0 progress, and more!|last=Lensmar |first=Ole |date=23 February 2016 |accessdate=13 October 2024}}</ref> and MuleSoft in 2017.<ref name=RAML>{{Cite web|url=https://www.infoq.com/news/2017/05/api-raml-oas |first1=Abel |last1=Avram |date=May 6, 2017 |title=The HTTP API space is Consolidating around OAS|website=InfoQ|access-date=2017-05-14}}</ref> Both have added support for the OAS.<ref>{{cite web|url=https://blog.apiary.io/We-ve-got-Swagger |website=Oracle Apiary |title=We've got Swagger|last=Nesetril |first=Jakub |date=18 January 2016 |accessdate=13 October 2024}}</ref><ref name=RAML />

===Release dates===

{| class="wikitable"

|-

! Version !! Date !! Notes<ref>{{cite web|url=https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md |website=GitHub |title=OpenAPI Specification Version 3.1.0|access-date=November 7, 2023}}</ref>

|-

|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

Line 77 ⟶ 92:

==Usage==

The OAS describes the format for OpenAPI Descriptions (OADs),<ref>{{cite web|titlename=OpenAPI Documentation: Glossary |website=Learn OpenAPI |url=https://learn.openapis.org/glossary.html |publisher=The OpenAPI Initiative |date=2023 |access-date=2024-09-17}}</ref> 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]]s. This helps keep the [[Software documentation|documentation]], client libraries and source code in sync.<ref>{{cite web|title=OpenAPI Documentation: Introduction |website=Learn OpenAPI |url=https://learn.openapis.org/introduction.html |publisher=The OpenAPI Initiative |date=2023 |access-date=2024-09-17}}</ref>

When an OpenAPI documentOAD is used to generate source code stubs for servers, the process is called [[Scaffold (programming)|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 object|mock]] the [[Server (computing)|server]] behavior and start testing right away.<ref>{{Cite book |last=Preibisch |first=Sascha |url=https://www.worldcat.org/oclc/1076234393 |publisher=Apress |title=API Development: A Practical Guide for Business Implementation Success |date=2018 |isbn=978-1-4842-4140-0 |___location=[Berkeley, CA] |oclc=1076234393 |quote=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.}}</ref> 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 programming|declarative]] resource specification, clients can understand and consume services without knowledge of server implementation or access to the server code.<ref name=git>{{Citestarted web|title = swagger-api/swagger-spec|url=https://github.com/swagger-api/swagger-spec/wiki|website = GitHub|access-date = 2015-12-01 |url-status=deviated |archive-url=https://archive.today/20160604140815/https://github.com/OAI/OpenAPI-Specification/wiki |archive-date= 4 Jun 2016 }}</ref>

==Tools that work with OpenAPI==

The OpenAPI Initiative maintains a list of implementations for version 3.0 of the specification.<ref>{{cite SmartBearweb|title=OpenAPI stillTooling brands|website=OpenAPI its OpenAPITooling |url=https://tools with the Swagger moniker.openapis.org/ The Swagger UI framework allows both developers and non|access-developersdate=2024-09-17 to|publisher=The interactOpenAPI with the API in a sandbox UI that gives insight into how the API responds to parameters and options. Swagger can handle both [[JSON]] and [[XML]].Initiative}}</ref name="git" />

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 [[Fork (software development)|forked]] the code into a project named OpenAPI Generator under the OpenAPI Tools organization.<ref>{{cite news|url=https://angular.schule/blog/2018-06-swagger-codegen-is-now-openapi-generator |first1=Johannes |last1=Hoppe |date=2018 |website=Angular.Schule |title=Swagger Codegen is now OpenAPI Generator|access-date=August 6, 2019}}</ref><ref>{{cite news|url=https://openapi-generator.tech/docs/fork-qna |website=OpenAPI Generator |title=Swagger Codegen Fork: Q&A|access-date=August 6, 2019}}</ref>

==Annual conference==

Line 114 ⟶ 127:

* [https://openapis.org/ OpenAPI Initiative (OAI) website]

* [https://events.linuxfoundation.org/openapi-asc/ API Specifications Conference (ASC) website]

* [http://swagger.io Swagger website]

* [https://github.com/OAI/OpenAPI-Specification OpenAPI Specification on GitHub]

* [https://github.com/APIs-guru/openapi-directory/ Directory of OpenAPI definitionsDescriptions]

* [https://learn.openapis.org/examples/ Example OpenAPI Descriptions on the OAI's official Learn OpenAPIs site]

* [https://marketplace.eclipse.org/content/openapi-studio-rich-oas3-editor OpenAPI Editor: A rich UI Eclipse OpenAPI (OAS) editor and studio to design, develop and test OAS3/OpenAPI]

* [https://docs.edination.com/hc/en-gb/articles/360012871880-OpenAPI-EDI-Extensions OpenAPI for EDI] the [[Electronic data interchange]]

* [https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml Example of a Petstore client/server specification.]

{{Use dmy dates|date=April 2019}}

Line 127 ⟶ 137:

[[Category:Application programming interfaces]]

[[Category:Markup languages]]

[[Category:JSON]]