|
| title = OpenAPI
| long_name = OpenAPI Specification
| image = OpenAPI Specification Logo Pantone.svg
| image_size =
| alt =
| 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 =
| license =
| copyright =
| 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>{{Citecite web|url=http://www.businesscloudnews.com/2015/11/06/linux-foundation-wants-to-extend-swagger-in-connected-buildings/ |title=LinuxOpenAPI FoundationDocumentation: wantsGetting toStarted extend|website=Learn SwaggerOpenAPI in connected buildings {{!}} Business Cloud News|archive-url=https://weblearn.archiveopenapis.org/web/20160506235108/http://www.businesscloudnews.com/2015/11/06/linux-foundation-wants-to-extend-swagger-in-connected-buildings/ |publisher=The OpenAPI Initiative |access-date=20162024-0409-22|archive-date=6 May 201617}}</ref> PreviouslyOriginally partdeveloped ofto support the [[Swagger (software)|Swagger]] framework, it became a separate project in 20162015, 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><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 Description (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.
By taking as an input swagger and some other tools can generate code, documentation, and test cases from OpenAPI Specification compliant files.
==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>
In November 2015, SmartBear announced that it was creatingdonating 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.<ref name="faqs">{{cite web |title=FAQ |url=https://www.openapis.org/faq#OAIFAQ-History |website=OpenAPI Initiative |access-date=12 November 2019}}</ref><ref>{{Cite news|url=http://www.programmableweb.com/news/%E2%80%8Bsmartbear-linux-foundation-launch-open-api-initiative-to-evolve-swagger/2015/11/10|title=SmartBear, Linux Foundation launch Open API Initiative to Evolve Swagger|date=2015-11-10|work=ProgrammableWeb|access-date=2016-04-21}}</ref><ref>{{Cite web|url=http://www.linuxfoundation.org/news-media/announcements/2015/11/new-collaborative-project-extend-swagger-specification-building|title=New Collaborative Project to Extend Swagger Specification for Building Connected Applications and Services|website=linuxfoundation.org|access-date=2016-04-22|url-status=dead|archive-url=https://web.archive.org/web/20160427104213/http://www.linuxfoundation.org/news-media/announcements/2015/11/new-collaborative-project-extend-swagger-specification-building|archive-date=2016-04-27}}</ref> SmartBear donated the Swagger specification to the new group. [[RAML (software)|RAML]] and [[API]] Blueprint were also under consideration by the group.<ref>{{Cite web|url=http://www.infoworld.com/article/3014506/apis/in-2016-the-need-for-an-api-meta-language-will-crystallize.html|title=In 2016, the need for an API meta-language will crystallize|last=Montcheuil|first=Yves de|website=InfoWorld|access-date=2016-04-25}}</ref><ref>{{Cite web|url=http://www.infoq.com/news/2016/04/Amazon-API-Gateway-Swagger|title=Amazon API Gateway Now Supports Swagger Definition Import|website=InfoQ|access-date=2016-04-25}}</ref>
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 SeptemberJuly 20162017, the APIOpenAPI WorldInitiative conferencereleased presentedversion an API Infrastructure award to SmartBear3.0.0 forof its ongoing work on Swaggerspecification.<ref>{{Cite web|url=https://swaggerwww.ioopenapis.org/blog/api-development2017/swagger07/26/the-winsoai-theannounces-2016the-apiopenapi-awardspecification-for3-api0-infrastruc/0 |titledate=SwaggerJuly wins26, the2017 2016|title=The APIOAI AwardAnnounces forthe APIOpenAPI InfrastructureSpecification 3.0.0|website=Swagger BlogOpenAPIs|access-date=2018-0704-2719}}</ref>
In JulyFebruary 20172021, the OpenAPI Initiative released version 3.01.0 of its specification.<ref>{{Cite web|url=https://www.openapislinux.orgcom/blognews/2017/07/26/the-oai-announces-the-openapi-specification-3-01-0-available-now |titledate=TheApril OAI26, Announces the2021 |title=OpenAPI Specification 3.01.0 Available Now|website=OpenAPIsLinux.com|access-date=20182021-04-1926}}</ref> [[MuleSoft]]Major changes in OpenAPI Specification 3.1.0 include JSON schema vocabularies alignment, thenew maintop-level contributorelements tofor thedescribing alternativewebhooks [[RESTfulthat are registered and managed out of band, support for identifying API Modelinglicenses using the standard Language]]SPDX (RAML)identifier, joinedallowance of descriptions alongside the OASuse of schema references and open-sourceda itschange APIto Modelingmake Frameworkthe tool,PathItems whichobject canoptional generateto OASsimplify documentscreation fromof RAMLreusable inputlibraries 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.infoqopenapis.comorg/newsblog/20172021/0502/api18/openapi-ramlspecification-oas3-1-released |date=February 18, 2021 |title=TheOpenAPI HTTPSpecification API3.1.0 spaceReleased|website=OpenAPI isInitiative|access-date=2021-02-18}}</ref><ref>{{Cite Consolidatingweb|url=https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0 around|first1=Phil OAS|last1=Sturgeon |date=February 16, 2021 |title=Migrating from OpenAPI 3.0 to 3.1.0|website=InfoQOpenAPI Initiative|access-date=20172021-0502-1416}}</ref>
===Consolidation of Formats===
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|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/|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|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|title=Migrating from OpenAPI 3.0 to 3.1.0|website=OpenAPI Initiative|access-date=2021-02-16}}</ref>
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 />
{| class="wikitable"
|-
! Version !! Date !! Notes<ref>{{cite web|url=httphttps://bgithub.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md |website=GitHub |title=OpenAPI Specification Version 3.01.40|access-date=AprilNovember 237, 20202023}}</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
==Usage==
The OAS describes the format for OpenAPI Descriptions (OADs),<ref name=glossary /> which can be used by a variety of applications, libraries, and tools.
Applications implemented based on OpenAPI interface files can 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 name=git>{{Cite web|title = swagger-api/swagger-spec|url=https://github.com/swagger-api/swagger-spec/wiki|website = GitHub|access-date = 2015-12-01}}</ref> ▼
▲Applications implementedcan baseduse onOADs OpenAPI interface files canto 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 name=git>{{ Citecite web|title =OpenAPI Documentation: Introduction |website= Learn OpenAPI swagger-api/swagger-spec|url=https:// githublearn. comopenapis.org/ swagger-api/swagger-spec/wikiintroduction.html | websitepublisher=The OpenAPI Initiative |date= 2023 GitHub|access-date = 20152024- 1209- 0117}}</ref>
When an OpenAPI document is used to generate source code stubs for servers, the process is called [[Scaffold (programming)|scaffolding]]. ▼
▲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 |urlpublisher=https://www.worldcat.org/oclc/1076234393Apress |title=API development Development: aA practicalPractical guideGuide for businessBusiness implementationImplementation successSuccess |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=gitstarted />
==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|title=Swagger Codegen is now OpenAPI Generator|access-date=August 6, 2019}}</ref><ref>{{cite news|url=https://openapi-generator.tech/docs/fork-qna|title=Swagger Codegen Fork: Q&A|access-date=August 6, 2019}}</ref>
==Annual conference==
* [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}}
{{Linux Foundation}}
[[Category:Software architecture]]
[[Category:Application programming interfaces]]
[[Category:Markup languages]]
[[Category:JSON]]
| 