Swagger 2.0 zu OpenAPI 3.0 migrieren

Wer ältere API-Repositories öffnet, trifft häufig noch auf Swagger 2.0. Das ist nicht ungewöhnlich. Swagger 2.0 war über Jahre der Standard und steckt deshalb in zahlreichen API-Landschaften. Gleichzeitig ist das Format seit 2014 eingefroren, während OpenAPI 3.0 seit 2017 etabliert ist. In modernen Tooling-Roadmaps wird Swagger 2.0 daher meist nur noch als Legacy-Format geführt. Für Teams, die eine API-Landschaft langfristig pflegen, stellt sich deshalb irgendwann nicht mehr die Frage, ob sie migrieren, sondern wann und wie sie es sauber tun.

Die Migration selbst muss in vielen Fällen kein Großprojekt werden. Die wichtigsten strukturellen Änderungen sind gut bekannt, etablierte Tools übernehmen einen großen Teil der Konvertierung, und die typischen Probleme ähneln sich von Projekt zu Projekt. Trotzdem lohnt sich eine saubere Vorbereitung. Denn gerade an den Stellen, an denen Konverter scheinbar automatisch arbeiten, entstehen später oft kleine Abweichungen, die Konsumenten, Generatoren oder Dokumentations-Tools betreffen können.

Was bei der Migration eigentlich passiert

Swagger 2.0 und OpenAPI 3.0 beschreiben zwar dieselbe Art von API, tun das aber mit unterschiedlichen Strukturen. Genau deshalb ist die Migration mehr als ein reines Format-Update. Die Spec wird an mehreren Stellen neu organisiert. Server-Informationen, Request-Bodies, Schemas, Responses und Security-Definitionen liegen nach der Konvertierung an anderen Stellen. Für die API selbst muss sich dadurch fachlich nichts ändern. Für Konsumenten, Generatoren, Mock-Server oder Dokumentations-Tools kann sich das Verhalten der migrierten Spec trotzdem ändern.

Der wichtigste Vorteil der Migration liegt im Tooling. OpenAPI 3.0 ist seit Jahren etabliert und wird von modernen Lintern, Code-Generatoren, Mocking-Tools und API-Plattformen meist zuerst unterstützt. Swagger 2.0 funktioniert in vielen Werkzeugen weiterhin, bekommt aber selten neue Funktionen oder Verbesserungen. Je länger eine API-Landschaft auf Swagger 2.0 bleibt, desto stärker wächst der Abstand zu aktuellen Tooling-Funktionen.

Ein zweiter Vorteil ist die klarere Modellierung. In OpenAPI 3.0 sind mehrere Punkte aufgeräumt, die in Swagger 2.0 in der Praxis oft zu Reibung geführt haben. Content-Negotiation wird pro Operation beschrieben, Request-Bodies sind sauber von Path- und Query-Parametern getrennt, und wiederverwendbare Elemente liegen konsistenter unter components. Dadurch wird die Spec leichter lesbar und verständlicher, besonders für Teams, die APIs über längere Zeit pflegen oder von mehreren Konsumenten nutzen lassen.

Strukturelle Änderungen im Detail

Die wichtigsten strukturellen Unterschiede zwischen Swagger 2.0 und OpenAPI 3.0 lassen sich gut eingrenzen. In fast jeder Migration ändern sich vor allem vier Bereiche. Dabei handelt es sich um Server-Definitionen, Schemas, Request-Bodies und Security-Schemas.

Die Server-Definition wird in OpenAPI 3.0 zusammengeführt. Während Swagger 2.0 host, basePath und schemes als separate Top-Level-Felder nutzt, beschreibt OpenAPI 3.0 diese Informationen gesammelt im servers-Block. Das ist nicht nur kompakter, sondern erlaubt auch mehrere Server-URLs, etwa für Staging, Production oder regionale API-Endpunkte.

Schemas werden aus definitions nach components.schemas verschoben. Die eigentliche Modellstruktur bleibt dabei häufig weitgehend erhalten. Wichtig ist aber, dass alle $ref-Verweise angepasst werden müssen. Aus /definitions/User wird zum Beispiel /components/schemas/User.

Request-Bodies werden in OpenAPI 3.0 nicht mehr als normale Parameter beschrieben. In Swagger 2.0 wurde dafür ein Parameter mit in: body verwendet. OpenAPI 3.0 nutzt stattdessen einen eigenen requestBody-Block. Dort wird auch festgelegt, welche Media-Types unterstützt werden, etwa application/json oder multipart/form-data. Die früheren globalen Felder consumes und produces verschwinden dadurch und werden in die jeweiligen content-Mappings der Operationen verschoben.

Auch die Security-Schemas bekommen in OpenAPI 3.0 einen neuen Platz. Was in Swagger 2.0 unter securityDefinitions stand, liegt jetzt unter components.securitySchemes. Bei OAuth 2.0 ändern sich außerdem einige Bezeichnungen: accessCode wird zu authorizationCode, application zu clientCredentials. Inhaltlich bleibt das Konzept erhalten, die Benennung ist aber näher an den heute üblichen OAuth-Begriffen.

Besonders sorgfältig ist die Übernahme von consumes und produces zu prüfen. In Swagger 2.0 konnten diese Angaben global für die gesamte Spec gesetzt werden. In OpenAPI 3.0 werden sie pro Operation in requestBody.content und responses.{code}.content beschrieben. Konverter lösen diesen Wechsel meist automatisch auf, setzen dabei aber gelegentlich Defaults, die nicht exakt zum tatsächlichen Verhalten der API passen. Genau diese Stellen sollten im Review gezielt kontrolliert werden.

Drei typische Fallstricke

Einige Probleme treten bei Migrationen von Swagger 2.0 zu OpenAPI 3.0 besonders häufig auf. Konverter erkennen viele dieser Fälle, lösen sie aber nicht immer so, wie es fachlich zur API passt. Wer weiß, an welchen Stellen typischerweise Reibung entsteht, spart später viel Zeit bei Review, Debugging und Konsumenten-Tests.

Der erste typische Fallstrick betrifft Datei-Uploads. In Swagger 2.0 werden Dateien häufig als formData-Parameter mit type: file modelliert. Dieses Konstrukt gibt es in OpenAPI 3.0 nicht mehr. Stattdessen werden Datei-Uploads über einen requestBody mit multipart/form-data beschrieben. Die Datei selbst wird als String mit format: binary modelliert.

Der zweite Fallstrick betrifft $ref-Verweise. Viele Swagger-2.0-Toolchains waren gegenüber externen, relativen oder zirkulären Referenzen relativ tolerant. OpenAPI-3.0-Tools prüfen hier oft strenger. Dadurch können Verweise fehlschlagen, die im alten Setup noch funktioniert haben. Die eigentliche Korrektur ist meist einfach, etwa durch eindeutigere Pfade oder eine bessere Aufteilung der Dateien. Zeit kostet vor allem das Auffinden der betroffenen Referenzen.

Der dritte Fallstrick liegt bei Beispielen. In Swagger-2.0-Specs steht oft ein einzelnes example pro Schema. OpenAPI 3.0 sieht dagegen mehrere benannte Beispiele über examples vor. Das ist flexibler, führt aber in der Praxis manchmal zu Darstellungsproblemen. Einige Dokumentations-Tools rendern den examples-Block nicht vollständig oder zeigen leere Beispielbereiche an, obwohl die Spec formal gültig ist. Deshalb sollten Beispiele nach der Migration nicht nur validiert, sondern auch in der generierten Dokumentation geprüft werden.

Ein weiterer Fallstrick wird oft erst spät sichtbar: nullable. Swagger 2.0 hatte dafür kein offizielles Konstrukt. Viele Specs nutzten deshalb Workarounds, etwa null als zusätzlichen Wert in einer enum-Liste. OpenAPI 3.0 führt dafür nullable: true ein. In OpenAPI 3.1 wird dieser Ansatz wiederum durch die JSON-Schema-konforme Schreibweise wie type: [string, "null"] ersetzt. Vor der Migration sollte deshalb klar sein, ob die Zielversion OpenAPI 3.0 oder OpenAPI 3.1 ist. Davon hängt ab, welches Nullable-Pattern verwendet wird.

Tooling für die Konvertierung

Für die Migration haben sich drei Werkzeug-Klassen etabliert. Sie lösen nicht alle dasselbe Problem, sondern eignen sich je nach Umfang, Zielbild und Arbeitsweise des Teams für unterschiedliche Szenarien.

swagger2openapi als CLI eignet sich besonders für direkte Konvertierungen einzelner Specs. Das Tool liest Swagger 2.0 ein und erzeugt OpenAPI 3.0.x. Für erste Tests, Einzelmigrationen oder eine Integration in Build-Prozesse ist das meist der pragmatischste Einstieg. Der Aufwand bleibt gering.

Der OpenAPI Generator kann die Konvertierung intern während der SDK- oder Server-Stub-Generierung übernehmen. Das ist vor allem dann sinnvoll, wenn die Spec hauptsächlich als Generator-Input dient und nicht als eigenständige, veröffentlichte API-Dokumentation gepflegt wird. Auch hier ist der Aufwand gering, allerdings sollte die erzeugte Ausgabe trotzdem geprüft werden.

Plattform-Konverter wie api-portal.io oder SwaggerHub sind besonders hilfreich, wenn mehrere Specs koordiniert migriert werden sollen. Sie verbinden die Konvertierung mit Vorschau, Diff-Ansicht und Validierung. Für Teams, die viele APIs betreuen oder einen nachvollziehbaren Audit-Trail brauchen, ist das oft besser geeignet als eine reine lokale CLI-Konvertierung. Der Aufwand liegt je nach Prozess zwischen gering und mittel.

Welches Werkzeug passt, hängt stark vom Bestand ab. Für eine einzelne Spec reicht häufig swagger2openapi, anschließend ergänzt durch Linter und Tests im Build. Bei größeren API-Landschaften reicht eine schnelle Konvertierung allein meist nicht aus. Wenn viele Specs migriert, verglichen und freigegeben werden müssen, ist eine Plattform-Lösung oft sinnvoller. Sie macht Versionsstände vergleichbar, zeigt Diffs nachvollziehbar an und unterstützt einen kontrollierten Review-Prozess.

In der Praxis bewährt sich ein zweistufiges Vorgehen. Die erste Spec wird bewusst manuell oder semi-automatisch migriert, damit das Team die typischen Probleme am eigenen Bestand kennenlernt. Danach übernimmt das gewählte Tool die mechanische Konvertierung. Im Review liegt der Fokus dann nicht auf jeder einzelnen Zeile, sondern auf den bekannten Risikostellen. Dazu gehören Media-Types, Request-Bodies, Datei-Uploads, $ref-Verweise, Beispiele, Security-Schemas und nullable-Felder. Das ist meist wirksamer als ein vollständiger, aber wenig fokussierter Review jeder Konverter-Ausgabe.

Migrations-Strategien für Bestand

Für bestehende API-Landschaften haben sich drei Migrations-Strategien bewährt. Welche davon passt, hängt vor allem von der Anzahl der APIs, der Abhängigkeit der Konsumenten und davon ab, wie eingespielt die Tooling-Praxis im Team ist.

1. Die erste Strategie ist ein Pilot. Dafür wird eine gut isolierte API ausgewählt und vollständig migriert. Das Team testet dabei die Tools, dokumentiert die auftauchenden Fallstricke und legt einen reproduzierbaren Workflow fest. Für viele Organisationen reichen drei bis sechs Wochen, um daraus einen belastbaren Prozess abzuleiten. Der Pilot ist die sicherste Strategie, skaliert aber naturgemäß langsamer als eine breit angelegte Migration.
2. Die zweite Strategie ist die inkrementelle Migration. Dabei werden Specs API für API migriert, zum Beispiel nach fachlicher Priorität, Kritikalität oder Konsumenten-Komplexität. Dieser Ansatz eignet sich besonders für mittelgroße Landschaften mit etwa zwanzig bis fünfzig APIs. Wichtig ist ein klarer Zeitpunkt, ab dem neue APIs nur noch in OpenAPI 3.x angelegt werden. Sonst wächst der Swagger-2.0-Bestand im Hintergrund weiter, während das Team bereits migriert.
3. Die dritte Strategie ist die Big-Bang-Migration. Dabei werden alle Specs in einem kurzen Zeitraum umgestellt, häufig innerhalb eines Sprints. Das ist nur bei sehr kleinen API-Landschaften mit fünf bis zehn APIs sinnvoll oder dann, wenn ohnehin eine größere Plattform-Migration ansteht. Ohne solchen Anlass ist ein Big Bang riskant, weil Konsumenten, Generatoren und Dokumentationsprozesse die Änderung gleichzeitig mittragen können müssen.

Validierung nach der Migration

Eine konvertierte Spec kann syntaktisch gültiges OpenAPI 3.0 sein und trotzdem fachliche Lücken enthalten. Genau deshalb endet die Migration nicht mit dem Konverter-Lauf. Jede migrierte Spec sollte anschließend validiert werden, technisch ebenso wie fachlich und aus Sicht der Konsumenten.

1. Der erste Schritt ist die Linter-Validierung. Ein Linter prüft die migrierte Spec anhand des geltenden Style Guides. Dabei fallen zum Beispiel Naming-Inkonsistenzen, fehlende Auth-Schemas, unvollständige Responses oder falsch gesetzte Media-Types auf. Solche Findings zeigen häufig genau die Stellen, an denen die Konvertierung etwas ausgelassen, vereinfacht oder ungünstig umorganisiert hat.
2. Der zweite Schritt ist die Contract-Test-Validierung. Contract-Tests prüfen, ob das tatsächliche Backend-Verhalten weiterhin zur migrierten Spec passt. Dadurch werden Abweichungen sichtbar, bevor Konsumenten sie bemerken. Wenn ein Konverter eine Endpoint-Beschreibung verändert, ein Schema-Detail verliert oder einen Media-Type falsch übernimmt, sollte der Contract-Test genau an dieser Stelle anschlagen.
3. Der dritte Schritt ist ein Konsumenten-Smoke-Test. Mindestens ein realer oder repräsentativer Konsument sollte die migrierte Spec anhand eines Mock-Servers oder des Staging-Backends testen, bevor die Änderung produktiv wird. Dieser Schritt ist vergleichsweise klein, deckt aber oft Probleme auf, die in CI-Tests nicht sichtbar werden. Beispiele sind Generator-Verhalten, Darstellungsfehler in der Dokumentation oder unerwartete Änderungen in Client-SDKs.
4. Der vierte Schritt ist die Kommunikation mit den Konsumenten. Auch wenn sich die API fachlich nicht ändert, sieht die Spec nach der Migration anders aus. Die Versionsangabe ist neu, Felder liegen an anderen Stellen, und manche Pfade in $ref-Verweisen ändern sich. Eine kurze Mitteilung mit Link zur neuen Spec-Version, Diff-Hinweis und erwarteter Auswirkung hilft, Missverständnisse zu vermeiden. Diese Kommunikation ist kein technischer Schritt, gehört aber genauso zur Migration wie Linter, Contract-Tests und Smoke-Tests.

Was kommt nach 3.0?

OpenAPI 3.0 ist das pragmatische Migrations-Ziel, weil das Tooling-Ökosystem hier am breitesten unterstützt wird. Die Versionslinie endet aber nicht bei 3.0. OpenAPI 3.1 hat 2021 die volle JSON-Schema-Konformität gebracht, was Datenmodellierung und Validierung enger zusammenführt. OpenAPI 3.2 ist seit September 2025 verfügbar und ergänzt unter anderem hierarchische Tags, eine offizielle QUERY-Methode und Server-Sent-Events-Support.

Für die meisten Teams lohnt sich der Sprung von 2.0 direkt auf 3.0. Wer Tooling und Linter im Griff hat, kann anschließend in einem zweiten Schritt auf 3.1 oder 3.2 weitergehen. Eingebettet in eine saubere Versionierungs-Strategie bleibt der Format-Sprung sauber dokumentiert und für Konsumenten nachvollziehbar.

Wie api-portal.io die Migration unterstützt

api-portal.io unterstützt Swagger 2.0 und OpenAPI 3.x parallel. Beim Import wird das Format automatisch erkannt. Swagger-2.0-Specs lassen sich bei Bedarf nach OpenAPI 3.x konvertieren. Die Diff-Ansicht zeigt, was sich zwischen Originalspec und konvertiertem Stand geändert hat. Zusätzlich wird die migrierte Spec vom integrierten Linter anhand der Style- und Security-Regeln geprüft. Teams können die Migration dadurch direkt im Portal nachvollziehen, prüfen und dokumentieren, ohne zwischen mehreren Toolchains wechseln zu müssen.

Der API Explorer bündelt die unterstützten Formate und interaktiven Funktionen.