Die OpenAPI-Spezifikation ( OAS ), ehemals bekannt als Swagger-Spezifikation , ist eine Spezifikation für eine maschinenlesbare Schnittstellendefinitionssprache zur Beschreibung, Erzeugung, Nutzung und Visualisierung von Webdiensten . [ 1 ] Ursprünglich zur Unterstützung des Swagger -Frameworks entwickelt, wurde sie 2015 zu einem eigenständigen Projekt unter der Leitung der OpenAPI Initiative, einem Open-Source-Kooperationsprojekt der Linux Foundation . [ 2 ] [ 3 ]

Eine OpenAPI Description (OAD) [ 4 ] stellt eine formale Beschreibung einer API dar, die von Tools verwendet werden kann, um Code, Dokumentation, Testfälle und mehr zu generieren.

Geschichte

Logo der OpenAPI Initiative, der Organisation, die die OpenAPI-Spezifikation unter der Linux Foundation entwickelt.

Die Entwicklung von Swagger begann Anfang 2010 durch Tony Tam, der beim Online-Wörterbuchunternehmen Wordnik arbeitete . [ 5 ]

Im März 2015 erwarb SmartBear Software die Open-Source-Swagger-API-Spezifikation von Reverb Technologies, der Muttergesellschaft von Wordnik. [ 6 ]

Im November 2015 gab SmartBear bekannt, die Swagger-Spezifikation an eine neue Organisation namens OpenAPI Initiative unter der Schirmherrschaft der Linux Foundation zu spenden . Zu den weiteren Gründungsmitgliedern gehörten 3scale , Apigee , Capital One , Google , IBM , Intuit , Microsoft , PayPal und Restlet. [ 7 ] [ 8 ]

Am 1. Januar 2016 wurde die Swagger-Spezifikation in OpenAPI Specification (OAS) umbenannt und in ein neues GitHub- Repository verschoben . [ 9 ]

Konsolidierung der Formate

Zwei ähnliche Technologien, MuleSofts RESTful API Modeling Language (RAML) und Apiarys API Blueprint, wurden etwa zur gleichen Zeit entwickelt wie die damals noch so genannte Swagger-Spezifikation.

Die Hersteller beider Formate traten später der OpenAPI-Initiative bei: Apiary im Jahr 2016 [ 10 ] und MuleSoft im Jahr 2017. [ 11 ] Beide haben die Unterstützung für OAS hinzugefügt. [ 12 ] [ 11 ]

Versionsverlauf

Im Juli 2017 veröffentlichte die OpenAPI Initiative die Version 3.0.0 ihrer Spezifikation. [ 13 ]

Im Februar 2021 veröffentlichte die OpenAPI Initiative Version 3.1.0. [ 14 ] Zu den wichtigsten Änderungen in der OpenAPI-Spezifikation 3.1.0 gehören die Angleichung der JSON-Schema-Vokabulare, neue Top-Level-Elemente zur Beschreibung von Webhooks, die außerhalb des regulären API-Verkehrs registriert und verwaltet werden, die Unterstützung der API-Lizenzidentifizierung mithilfe des Standard-SPDX-Identifikators, die Zulassung von Beschreibungen neben Schema-Referenzen sowie die Änderung, das PathItems-Objekt optional zu gestalten, um die Erstellung wiederverwendbarer Komponentenbibliotheken zu vereinfachen. [ 15 ] [ 16 ] [ 17 ]

Im September 2025 veröffentlichte die OpenAPI Initiative Version 3.2.0 des OAS. [ 18 ] Zu den bemerkenswerten Neuerungen gehören strukturierte Tags, erstklassige Unterstützung für Streaming-Medientypen, Unterstützung für beliebige HTTP-Methoden, klarere Beispielsemantik für Serialisierungen, Verbesserungen des OAuth2-Geräteablaufs und der Metadaten sowie präzisierte Pfadvorlagen und Routing-Semantik. [ 19 ]

Veröffentlichungstermine

VersionDatumAnmerkungen [ 20 ]
3.2.0 19.09.2025 Veröffentlichung der OpenAPI-Spezifikation 3.2.0
3.1.2 19.09.2025 Patch-Release der OpenAPI-Spezifikation 3.1.2
3.1.1 24.10.2024 Patch-Release der OpenAPI-Spezifikation 3.1.1
3.1.015.02.2021Veröffentlichung der OpenAPI-Spezifikation 3.1.0
3.0.4 24.10.2024 Patch-Release der OpenAPI-Spezifikation 3.0.4
3.0.3 20.02.2020 Patch-Release der OpenAPI-Spezifikation 3.0.3
3.0.2 08.10.2018 Patch-Release der OpenAPI-Spezifikation 3.0.2
3.0.1 06.12.2017 Patch-Release der OpenAPI-Spezifikation 3.0.1
3.0.026.07.2017Veröffentlichung der OpenAPI-Spezifikation 3.0.0
2.008.09.2014Veröffentlichung von Swagger 2.0
1.214.03.2014Erste Veröffentlichung des offiziellen Dokuments
1.122.08.2012Veröffentlichung von Swagger 1.1
1.010.08.2011Erste Veröffentlichung der Swagger-Spezifikation

Verwendung

Die OAS beschreibt das Format für OpenAPI Descriptions (OADs), [ 4 ] die von einer Vielzahl von Anwendungen, Bibliotheken und Werkzeugen verwendet werden können.

Anwendungen können OADs verwenden, um automatisch Dokumentationen von Methoden, Parametern und Datenmodellen zu generieren . Dies trägt dazu bei , Dokumentation , Clientbibliotheken und Quellcode synchron zu halten. [ 21 ]

Wenn ein OAD verwendet wird, um Quellcode-Stubs für Server zu generieren, wird dieser Prozess als Scaffolding bezeichnet .

Beziehungen zu Softwareentwicklungspraktiken

Das Paradigma, zuerst einen API-Vertrag zu vereinbaren und anschließend die Geschäftslogik zu programmieren – im Gegensatz zur Vorgehensweise, zuerst das Programm zu programmieren und dann im Nachhinein eine Beschreibung seines Verhaltens als Vertrag zu verfassen –, wird als Contract-First-Entwicklung bezeichnet. Da die Schnittstelle vor dem Schreiben des Codes festgelegt wird, können nachfolgende Entwickler das Serververhalten simulieren und sofort mit dem Testen beginnen. [ 22 ] In diesem Sinne ist Contract-First-Entwicklung auch eine Form des Shift-Left-Testings .

Merkmale

Die OpenAPI-Spezifikation ist sprachunabhängig. Dank der deklarativen Ressourcenspezifikation von OpenAPI können Clients Dienste verstehen und nutzen, ohne Kenntnisse der Serverimplementierung oder Zugriff auf den Servercode zu benötigen. [ 1 ]

Konferenzen und Konferenzthemen

Die OpenAPI Initiative sponserte APIStrat von 2017 bis 2019 und wandelte sie von 2020 bis 2022 in die API Specifications Conference (ASC) um. [ 23 ] Seit 2023 sponsert die Initiative stattdessen OpenAPI-Tracks auf mehreren Konferenzen im Laufe des Jahres. [ 24 ]

Siehe auch

Referenzen

  1. ^ a b „OpenAPI-Dokumentation: Erste Schritte“ . OpenAPI lernen . Die OpenAPI-Initiative . Abgerufen am 17. September 2024 .
  2. ^ „Neues Gemeinschaftsprojekt zur Erweiterung der Swagger-Spezifikation für die Entwicklung vernetzter Anwendungen und Dienste“ . Archiviert vom Original am 31. Oktober 2023.
  3. ^ „OpenAPI Initiative Charter“ . OpenAPI Initiative . Archiviert vom Original am 26. Januar 2025. Abgerufen am 12. November 2019 .
  4. ^ a b „OpenAPI-Dokumentation: Glossar“ . OpenAPI lernen . Die OpenAPI-Initiative. 2023. Abgerufen am 17. September 2024 .
  5. ^ „Swagger-Erfinder wechselt zu SmartBear“ . 28. September 2015. Abgerufen am 6. August 2019 .
  6. ^ „SmartBear übernimmt die Schirmherrschaft für das Open-Source-Projekt Swagger API“ . SmartBear . Abgerufen am 25. März 2015 .
  7. ^ „FAQ“ . OpenAPI Initiative . Abgerufen am 12. November 2019 .
  8. ^ „Neues Gemeinschaftsprojekt zur Erweiterung der Swagger-Spezifikation für die Entwicklung vernetzter Anwendungen und Dienste“ . linuxfoundation.org . Archiviert vom Original am 27. April 2016. Abgerufen am 22. April 2016 .
  9. ^ OpenAPI Initiative. „OpenAPI Specification“ . GitHub . Abgerufen am 12. November 2019 .
  10. ^ Lensmar, Ole (23. Februar 2016). „OAI-Update – neue Mitglieder, Fortschritte bei der OpenAPI-Spezifikation 3.0 und mehr!“ . Die OpenAPI-Initiative . Abgerufen am 13. Oktober 2024 .
  11. ^ a b Avram, Abel (6. Mai 2017). „Der HTTP-API-Bereich konsolidiert sich um OAS“ . InfoQ . Abgerufen am 14. Mai 2017 .
  12. ^ Nesetril, Jakub (18. Januar 2016). „Wir haben Swagger“ . Oracle Apiary . Abgerufen am 13. Oktober 2024 .
  13. ^ „Die OAI kündigt die OpenAPI-Spezifikation 3.0.0 an“ . OpenAPIs . 26. Juli 2017. Abgerufen am 19. April 2018 .
  14. ^ „OpenAPI-Spezifikation 3.1.0 jetzt verfügbar“ . Linux.com . 26. April 2021. Abgerufen am 26. April 2021 .
  15. ^ Charboneau, Tyler (7. April 2021). „Was ist neu in OpenAPI 3.1.0?“ . Nordic APIs . Abgerufen am 7. April 2021 .
  16. ^ „OpenAPI-Spezifikation 3.1.0 veröffentlicht“ . OpenAPI Initiative . 18. Februar 2021. Abgerufen am 18. Februar 2021 .
  17. ^ Sturgeon, Phil (16. Februar 2021). „Migration von OpenAPI 3.0 zu 3.1.0“ . OpenAPI Initiative . Abgerufen am 16. Februar 2021 .
  18. ^ „Ankündigung von OpenAPI v3.2“ . Der OpenAPI Initiative Blog . 23. September 2025. Abgerufen am 15. Juni 2026 .
  19. ^ „Was ist neu in der OpenAPI-Spezifikation v3.2.0?“ . Nordic APIs . 27. Januar 2026 . Abgerufen am 15. Juni 2026 .
  20. ^ „OpenAPI-Spezifikation Version 3.2.0“ . Veröffentlichungen der OpenAPI-Initiative . Abgerufen am 15. Juni 2026 .
  21. ^ „OpenAPI-Dokumentation: Einführung“ . OpenAPI lernen . Die OpenAPI-Initiative. 2023. Abgerufen am 17. September 2024 .
  22. ^ Preibisch, Sascha (2018). API-Entwicklung: Ein praktischer Leitfaden für die erfolgreiche Implementierung im Unternehmen . [Berkeley, CA]: Apress. ISBN 978-1-4842-4140-0OCLC 1076234393 . Wenn das Swagger -  Dokument (oder auch ein anderes maschinenlesbares Dokument) verfügbar ist, können die Teammitglieder gleichzeitig mit der Bearbeitung ihres jeweiligen Projektteils beginnen.
  23. ^ „Einführung der ASC, der API Specifications Conference“ . OpenAPI Initiative Blog . 8. Mai 2019. Abgerufen am 15. Juni 2026 .
  24. ^ „Aufruf zur Einreichung von Vorschlägen: OAI Track bei den API Days London. Datum: 13.–14. September 2023. Ort: 155 Bishopsgate, London, Vereinigtes Königreich . “ OpenAPI Initiative Blog . Abgerufen am 15. Juni 2026 .

Bibliographie

  • Haupt, F.; Karastoyanova, D.; Leymann, F.; Schroth, B. (2014). Ein modellgetriebener Ansatz für REST-konforme Dienste . ICWS 2014. IEEE International Conference on Web Services 2014. S.  129–136 . doi : 10.1109/ICWS.2014.30 . ISBN 978-1-4799-5054-6Die
  • Pautasso, Cesare (2021). Schöne APIs . LeanPub. S. 100.