OpenAPI vs Swagger

In API-Repositories, die uns regelmäßig begegnen, taucht dieselbe Konstellation immer wieder auf. Die Spec beginnt mit swagger: "2.0", Swagger UI rendert sie unter /openapi im Browser, im Confluence-Wiki heißt dieselbe Datei einmal „Swagger-File" und auf der nächsten Seite „OpenAPI-Spec". Im Standup fragt früher oder später jemand, ob Swagger 2026 überhaupt noch zeitgemäß ist.

Wir sehen diese Konstellation quer durch Banken, Industriekonzerne und Behörden, über sehr unterschiedliche Tech-Stacks und Reifegrade hinweg. Die Verwirrung ist auffällig stabil. Sie hat eine konkrete Ursache.

Eine Spezifikation, die einst Swagger hieß, wurde 2015 in OpenAPI umbenannt. Die Tools blieben bei ihrer alten Marke. Beide Namen werden seitdem parallel verwendet, oftmals in derselben Codezeile.

Wer heute „OpenAPI vs Swagger" googelt, findet in den meisten Treffern eine Antwort, die halb in der Geschichte stecken bleibt und halb in einem unfertigen Versionsvergleich.

Eine kurze Geschichte vom Swagger zur OpenAPI Specification

Tony Tam veröffentlichte 2011 die erste Version der Swagger Specification, eingebettet in das Wordnik-Backend, das damals deutlich mehr API-Verkehr hatte als die meisten Wörterbuch-Plattformen. Die Spezifikation war pragmatisch und maschinenlesbar entworfen. Sie verbreitete sich schnell, weil sie ein Problem löste, das alle hatten und niemand strukturiert beschrieb.

Swagger 2.0 erschien 2014 und wurde innerhalb kurzer Zeit zum De-facto-Standard für API-Beschreibungen. Im November 2015 übergab SmartBear die Spezifikation an die Linux Foundation. Im Zuge dessen entstand die OpenAPI Initiative, ein offenes Konsortium, das den Standard fortan trägt. Die Spezifikation selbst wurde 2016 in OpenAPI Specification umbenannt, während die Marke Swagger bei SmartBear blieb und auf die Tool-Familie bezogen wurde.

Mit der OpenAPI Initiative schlossen sich Unternehmen an, die zusammen einen Großteil der weltweiten API-Volumen verantworten. Google, Microsoft, IBM, Salesforce, PayPal und Atlassian gehörten zu den Gründungs- und frühen Premier-Mitgliedern, später kamen Unternehmen wie Adobe, Intuit und Oracle dazu. Diese breite Trägerschaft sorgte dafür, dass die Spezifikation nicht mehr von einem einzelnen Anbieter abhing und in den nächsten Iterationen herstellerneutral weiterentwickelt wurde.

Das erste Major-Release unter dem neuen Namen war OpenAPI 3.0.0 im Juli 2017. Es war kein kleines Update, sondern eine strukturelle Überarbeitung, die viele frühere Designentscheidungen korrigierte. Patch-Versionen 3.0.1, 3.0.2 und 3.0.3 folgten in den Jahren danach. Im Februar 2021 erschien OpenAPI 3.1.0 mit voller JSON-Schema-Kompatibilität, Webhooks und expliziter Unterstützung von Null-Werten. Im September 2025 folgte OpenAPI 3.2.0 mit hierarchischen Tags, der QUERY-Methode und nativer Unterstützung für streamende APIs. Die Version bleibt backward-kompatibel zu 3.0 und 3.1.

Heute laufen beide Namen parallel weiter. Die Spezifikation heißt OpenAPI, die Tools heißen Swagger, und in derselben Codezeile tauchen oftmals beide auf.

Was heute was ist. Die Begriffs-Karte

„Swagger" steht 2026 in den meisten Fällen für ein Werkzeug, „OpenAPI" für die Spezifikation, die einst Swagger hieß. Die folgende Übersicht ordnet die Begriffe konkret zu.

Die doppelte Sprache hat zwei Gründe. SmartBear hält weiter die Marke Swagger und entwickelt darunter aktiv Tools, vor allem Swagger UI und SwaggerHub. Die OpenAPI Initiative trägt den Standard, hat aber kein eigenes Tooling-Portfolio. Hinzu kommt eine schlichte Sprachgewohnheit. Wer zehn Jahre lang Swagger-Files geschrieben hat, sagt selten von einem Tag auf den anderen OpenAPI-Files.

Swagger ist heute eine Marke, OpenAPI ein offener Standard. Wer „Swagger" sagt, meint in der Regel ein Tool aus der SmartBear-Familie oder das alte Spec-Format 2.0. „OpenAPI" bezeichnet das Format selbst, also die YAML- oder JSON-Datei, mit der moderne APIs beschrieben werden.

Was sich zwischen den Versionen geändert hat

Im Alltag sind vier Versionssprünge im Spiel. Swagger 2.0 (2014) brachte das Format zum De-facto-Standard, OpenAPI 3.0 (2017) räumte strukturell auf, OpenAPI 3.1 (2021) zog die JSON-Schema-Kompatibilität nach, und OpenAPI 3.2 (2025) ergänzte hierarchische Tags, die QUERY-Methode und Streaming-Support. Welche Auswirkungen ein Sprung hat, hängt vom bestehenden Tooling-Stand ab.

Strukturelle Überarbeitung von Swagger 2.0 zu OpenAPI 3.0

Der Wechsel von 2.0 zu 3.0 verändert die Topologie der Spec. Server-Definitionen, Schemas, Sicherheitsmechanismen und Request-Bodies wurden neu organisiert, nicht nur umbenannt.

Die wichtigsten Umbenennungen fallen auf vier Stellen. host, basePath und schemes sind in servers zusammengefasst. definitions heißt jetzt components.schemas. consumes und produces werden nicht mehr global gesetzt, sondern pro Operation über requestBody und responses.content. securityDefinitions heißt components.securitySchemes.

OpenAPI 3.1 ergänzt JSON Schema, Webhooks und null-Types

3.1 ist kleiner als der Sprung davor, aber an den richtigen Stellen folgenreich. Drei Änderungen sind relevant.

• OpenAPI 3.1 ist ein vollständig konformer JSON-Schema-Dialekt. Bisher waren OpenAPI-Schemas eine eigene, leicht abweichende Variante. In 3.1 darf jedes JSON-Schema-Konstrukt direkt verwendet werden, einschließlich anyOf, oneOf, allOf und $dynamicRef.
• Webhooks haben in 3.1 ein eigenes Top-Level-Konstrukt. Bisher wurden Callbacks oder reine Event-APIs entweder verbogen oder ausgelagert. Mit 3.1 lassen sich asynchrone Trigger sauber im selben Dokument beschreiben.
• null ist explizit. In 3.0 musste über nullable: true umständlich modelliert werden. In 3.1 reicht type: [string, "null"], was JSON-Schema-konform ist.

Ein Webhook in OpenAPI 3.1 sieht in einer minimalen Form so aus.

Vor 3.1 musste dieser Anwendungsfall entweder als Callback in einer regulären Operation modelliert oder in eine separate AsyncAPI-Spezifikation ausgelagert werden. Beide Wege sind weiterhin gültig, der Webhook-Block ist die direkte Alternative für reine Event-APIs.

Welche Version wann

Die Frage taucht in zwei Situationen auf. Bei neuen APIs als Wahl zwischen OpenAPI 3.1 und 3.2, bei Bestandssystemen meist als Migrationsfrage von 2.0 oder 3.0.

Der zeitliche Korridor für eine 2.0-Migration liegt erfahrungsgemäß bei zwölf bis achtzehn Monaten in einer mittelgroßen API-Landschaft mit zwanzig bis fünfzig aktiven APIs. Den Unterschied macht weniger das exakte Migrationsdatum als der Stichtag, ab dem neue APIs nur noch in 3.x angelegt werden. Ohne diesen Stichtag wandert der Bestand still weiter in 2.0, und die Migrationskurve verflacht, statt zu sinken.

Migration von Swagger 2.0 zu OpenAPI 3.x

Eine Migration von Swagger 2.0 nach OpenAPI 3.0 lässt sich in den meisten Fällen in wenigen Tagen erledigen. Der Aufwand liegt selten in den strukturellen Änderungen, sondern in den drei oder vier Fallstricken, die in fast jedem Bestand auftauchen.

Fünf Stellen ändern sich in der Regel. Die Server-Definition zieht aus host, basePath und schemes in einen servers-Block um. Schemas wandern aus definitions in components.schemas. Request-Bodies werden nicht mehr als Parameter mit in: body modelliert, sondern in requestBody mit content-Mapping. Responses bekommen eine content-Ebene mit Media-Types, statt global über produces definiert zu werden. Sicherheitsmechanismen wandern aus securityDefinitions in components.securitySchemes.

Eine typische kritische Stelle zeigt sich beim Datei-Upload. In Swagger 2.0 ist das ein einfacher Parameter, in OpenAPI 3.0 ein vollständiger requestBody.

Zwei Werkzeuge haben sich für die Konvertierung etabliert. swagger2openapi als CLI ist die direkte Standardlösung. OpenAPI Generator kann während der SDK-Generierung intern konvertieren, was nützlich ist, wenn die Spec primär als Generator-Input dient.

Wer in derselben Migration gleich auf 3.1 oder 3.2 zielt, hat den 3.0-Schritt damit ohnehin gemacht. Der Sprung von 3.0 über 3.1 nach 3.2 ist deutlich kleiner als der Sprung von 2.0 zu 3.0 und bleibt meistens reine Schema-Anpassung, weil 3.1 und 3.2 backward-kompatibel sind.

Ist Swagger 2026 noch relevant?

Die Frage stellt sich vor allem dann, wenn ein Spec-Tooling neu evaluiert wird oder ein Bestand auf 2.0 in eine größere Modernisierung läuft. Vier Aspekte tauchen in dieser Diskussion immer wieder auf. Swagger UI, Swagger Codegen, das Format Swagger 2.0 selbst und SwaggerHub als kommerzielles Produkt.

Wird Swagger UI noch genutzt?

Ja. Swagger UI ist faktisch der Standard-Renderer für OpenAPI-Dokumente und läuft in der Größenordnung von hunderttausenden öffentlich erreichbaren Repositories und API-Endpunkten. Spring REST, FastAPI, Express, ASP.NET Core, Flask und Quarkus liefern eine Swagger-UI-Integration entweder direkt mit oder als ein-Zeilen-Setup. Konkurrenten wie Redoc oder Scalar gewinnen Marktanteile vor allem in Branding-getriebenen Developer-Portalen, in denen das visuelle Auftreten ein Produktmerkmal ist. Im technischen Alltag, wo es um schnelles Rendern einer Spec geht, ersetzen sie Swagger UI nicht.

Ist Swagger Codegen noch zeitgemäß?

Bedingt. Swagger Codegen wurde in den letzten Jahren von OpenAPI Generator weitgehend abgelöst. OpenAPI Generator ist 2018 als Community-Fork entstanden und wird seitdem deutlich aktiver gepflegt, mit über fünfzig Sprach- und Framework-Templates und mehreren Releases pro Jahr. Neue Projekte starten meistens direkt mit OpenAPI Generator. Bestände auf Swagger Codegen laufen weiter, der Pflegeabstand wächst aber Jahr für Jahr, und neue Sprach-Targets erscheinen praktisch ausschließlich im Generator-Fork.

Soll man Swagger 2.0 noch nutzen?

Für neue APIs nicht mehr. Swagger 2.0 wird seit 2014 nicht mehr weiterentwickelt. Für Bestandssysteme besteht kein akuter Migrationsdruck, aber die mittelfristige Migration auf 3.x sollte eingeplant sein. Neue Tools, neue Linter und neue Generator-Templates testen 3.x zuerst, ältere 2.0-Pfade dünnen kontinuierlich aus. Wer 2.0 weiter pflegt, sollte zumindest dokumentieren, dass es ein Bestandsformat ist und keine neue Spec mehr darin entsteht. Sonst entsteht in zwei Jahren eine 2.0-Erweiterung, die niemand mehr migrieren will.

Was ist mit SwaggerHub?

SwaggerHub ist ein kommerzielles Produkt von SmartBear, kein offener Standard. Es ist eine Option unter mehreren API-Plattformen. Andere Optionen sind api-portal.io, Stoplight, Postman oder Bump.sh. Die Wahl hängt von Faktoren wie Multi-Tenant-Isolation, Governance-Modell, Integration in CI/CD, Hosting-Modell (SaaS oder On-Premises) und kommerziellem Modell ab. SwaggerHub ist tooling-nah am Swagger-Ökosystem und punktet vor allem dann, wenn ein Team ohnehin mit Swagger UI und Swagger Editor arbeitet. Andere Plattformen setzen breiter auf das gesamte API-Lifecycle-Management, von Spec-Verwaltung über Linter bis Konsumenten-Onboarding.

Wie api-portal.io OpenAPI und Swagger handhabt

In api-portal.io werden OpenAPI 3.x und Swagger 2.0 parallel unterstützt. Beim Import erkennt die Plattform das Format automatisch und konvertiert Swagger 2.0 bei Bedarf nach OpenAPI 3.x. Der API Explorer rendert beide Formate in einer einheitlichen Oberfläche, der API Linter prüft beide gegen denselben Style Guide.

Der API Explorer zeigt, wie beide Spec-Formate dargestellt werden.