OpenAPI 3.2 kennenlernen

OpenAPI 3.2 kennenlernen

0:00 Am ersten Tag haben wir entworfen — Ressourcen, Methoden, Fehler. All das existiert bisher in Köpfen und in Notizen. Heute machen wir es maschinenlesbar. OpenAPI ist der De-facto-Standard dafür, und der Unterschied zu einer Dokumentationsseite ist fundamental: Aus einem OpenAPI-Dokument entstehen Dokumentation, Mock Server, Client-Code und Tests.

0:22 Es ist kein Beiwerk, das man am Ende schreibt, sondern die Quelle, aus der der Rest fällt. In diesem Modul lernen wir seinen Aufbau kennen — und was die Fassung 3.2 seit letztem Jahr dazugebracht hat.

OpenAPI 3.2 kennenlernen

0:35 Der zweite Tag dreht sich ganz um den Vertrag als ausführbares Artefakt. Wir beginnen mit dem Aufbau eines OpenAPI-Dokuments, sehen uns an, wie eine einzelne Operation beschrieben wird, und klären dann die Versionsfrage: Was bringt 3.2, und was bedeutet es für Ihre Werkzeugkette. Am Ende des Moduls beschreiben Sie die Bestell-Endpunkte der Hofkiste selbst.

Aufbau eines OpenAPI-Dokuments

0:57 Fangen wir mit der Landkarte an. Ein OpenAPI-Dokument sieht auf den ersten Blick unübersichtlich aus, hat aber eine überschaubare Struktur — sieben Felder auf oberster Ebene, und der Rest hängt darunter. Wenn Sie diese sieben Felder kennen, können Sie jedes OpenAPI-Dokument lesen, egal wie groß es ist. Alles Weitere ist Detail innerhalb dieser Struktur.

1:19 Eine Sache überrascht viele: Ein gültiges OpenAPI-Dokument braucht gar keine Pfade. Es genügt eines von dreien — paths, webhooks oder components. Das heißt, Sie können eine reine Komponentensammlung veröffentlichen, etwa gemeinsame Schemas und Fehlerformate für alle APIs Ihres Hauses, und die einzelnen Dienste verweisen darauf.

1:39 Genau so löst man das Problem, dass jedes Team seine eigene Adressdarstellung erfindet. Und webhooks als eigene Kategorie zeigt, dass OpenAPI inzwischen auch die andere Richtung beschreibt: Aufrufe, die von Ihnen ausgehen. Achten Sie auf die Fußnote, denn dort steckt eine echte Fehlerquelle. Es gibt zwei Versionsangaben in diesem Dokument, und sie meinen völlig Verschiedenes.

2:03 Das Feld openapi ganz oben nennt die Version der Spezifikation — also die Sprache, in der Sie schreiben. Die Version innerhalb von info gehört Ihrer API. Wer das verwechselt, hat entweder eine API in Version 3.2.0 oder eine Spezifikation in Version 2.3.0, und beides führt zu erstaunlich langen Diskussionen im Review. Der Rest der Tabelle ist Handwerk.

2:26 Zwei Dinge lohnen den Blick. Erstens: Das ist eine YAML-Datei im Repository, kein Export aus einem Werkzeug. Sie hat eine Historie, sie geht durch Pull Requests, sie wird geprüft — genau das meint der Grundsatz, den Vertrag wie Quelltext zu behandeln. Zweitens das Feld name am Server: Das ist neu in 3.2 und benennt die Umgebung. Bisher standen dort nur Adressen, und welche davon Produktion war, wusste man aus dem Kommentar.

2:54 Jetzt können Werkzeuge es lesen. Der Grundsatz dahinter ist derselbe wie im Code: Wiederholung ist der Anfang von Abweichung. Die OpenAPI-Initiative empfiehlt ausdrücklich, wiederholte Strukturen in components zu ziehen und über Verweise einzubinden. Der praktische Gewinn zeigt sich beim Fehlerformat aus Modul 4: Wenn es an einer Stelle steht, ändern Sie es einmal.

3:16 Wenn es in vierzig Operationen kopiert ist, ändern Sie es siebenunddreißigmal und übersehen den Rest. Besonders wertvoll sind securitySchemes — Anmeldeverfahren gehören genau einmal beschrieben. Der dritte Punkt ist der peinlichste und passiert trotzdem regelmäßig: In servers steht die Entwicklungsadresse, und so geht das Dokument nach draußen.

3:37 Consumer generieren daraus Clients, die gegen Ihre Testumgebung laufen. Der vierte Punkt ist subtiler und hat spätere Folgen: Die Version in info wird nie erhöht. Damit verlieren Sie die Möglichkeit, Fassungen des Vertrags voneinander zu unterscheiden — und in Modul 13, wenn wir Änderungen vergleichen, fehlt Ihnen der Bezugspunkt.

Operationen beschreiben

3:56 Gehen wir eine Ebene tiefer. Eine Operation ist die kleinste sinnvolle Einheit in OpenAPI — und die Stelle, an der sich entscheidet, ob aus Ihrem Dokument brauchbarer Code entstehen kann. Denn hier entscheidet sich, ob aus Ihrem Dokument brauchbarer Client-Code entstehen kann — und ob ein Consumer überhaupt weiß, was ihn erwartet.

4:16 Eine Operation ist schlicht die Kombination aus Pfad und Methode — GET auf eine Bestellung ist eine, POST auf die Sammlung eine andere. Bemerkenswert ist, was Pflicht ist: das responses-Objekt. Alles andere darf fehlen, aber mindestens eine Antwort müssen Sie beschreiben. Das ist keine Formalie, sondern eine kleine Erziehungsmaßnahme des Standards: Eine Operation ohne beschriebene Antwort ist für den Consumer wertlos.

4:41 Er weiß dann zwar, dass er etwas aufrufen kann, aber nicht, was zurückkommt. Zwei Details verdienen Aufmerksamkeit. Die operationId ist mehr als eine Beschriftung — sie ist der Name, unter dem Codegeneratoren später die Methode anlegen. Wer sie weglässt, überlässt dem Generator die Namensgebung, und das Ergebnis ist selten schön. Wer sie später ändert, benennt in jedem erzeugten Client eine Methode um.

5:06 Das zweite Detail ist der Verweis auf die Antwort: Die Beschreibung der Bestellung steht nicht hier, sondern in components. Genau das Muster, das wir eben besprochen haben — einmal beschreiben, überall verweisen. Die Aufzählung ist Handwerkswissen, aber zwei Punkte lohnen die Aufmerksamkeit. Neu in 3.2 ist querystring — damit lässt sich die gesamte Abfragezeichenkette als ein Wert beschreiben.

5:31 Das klingt exotisch und löst ein reales Problem: Filtersprachen, die sich nicht in einzelne Parameter zerlegen lassen. Der letzte Punkt ist eine Regel, an der Validatoren gern anschlagen: Ein Parameter hat entweder schema oder content, niemals beides. Schema ist der Normalfall, content brauchen Sie nur, wenn ein Parameter selbst strukturierte Daten trägt.

5:53 Der zweite Punkt ist der häufigste und der folgenreichste: Nur der Erfolgsfall ist beschrieben. Damit ist der halbe Vertrag unvollständig, denn Fehlerantworten sind die Zusagen, auf die sich ein Consumer im Betrieb verlässt. Der dritte Punkt ist ein Klassiker der Pflichtübung — eine Beschreibung, die den Feldnamen wiederholt, ist keine Beschreibung. Bei bestellId steht dann "Die Bestell-ID".

6:17 Das erzeugt Dokumentation ohne Information und sollte im Review auffallen.

Von OpenAPI 3.1 zu 3.2

6:22 Kommen wir zur Versionsfrage. Seit September 2025 gibt es OpenAPI 3.2, und die Frage im Alltag lautet nicht, ob man umsteigen sollte, sondern wann die Werkzeuge so weit sind. Inhaltlich ist der Umstieg unspektakulär. Die eigentliche Frage lautet, ob Ihre Werkzeugkette schon mitspielt — und was Sie tun, wenn nicht. Die gute Nachricht steht gleich im ersten Satz: OpenAPI 3.2 bringt keine inkompatiblen Änderungen.

6:49 Bestehende 3.1-Dokumente gelten unverändert weiter, sobald Sie die Versionsnummer anheben. Das ist bemerkenswert für einen Standard und macht den Umstieg zu einer Frage der Werkzeuge, nicht der Inhalte. Der Grund, warum viele Häuser trotzdem noch auf 3.1 stehen, ist genau das: Der Generator, die Dokumentationsseite oder das Gateway kennen die neue Fassung noch nicht — und dann nützt Ihnen ein modernes Dokument wenig.

7:14 Vier Neuerungen mit sehr unterschiedlichem Alltagsnutzen. Die Tag-Hierarchie über parent ist die unspektakulärste und wird trotzdem am schnellsten dankbar angenommen — sie bringt Ordnung in Dokumentationsseiten großer APIs. Das Feld $self gibt dem Dokument eine eigene Kennung, was für Verweise zwischen Dokumenten zählt. Die Methode QUERY adressiert ein altes Ärgernis: komplexe Filter, die nicht in eine URL passen.

7:39 Und itemSchema schließt eine echte Lücke, denn Datenströme ließen sich in OpenAPI bisher schlicht nicht beschreiben. Die Gegenüberstellung zeigt nicht besser gegen schlechter, sondern verfügbar gegen wünschenswert. Zeile eins ist der Grund, warum viele bleiben, wo sie sind: 3.1 versteht jedes Werkzeug. Die anderen Zeilen zeigen, was Sie liegen lassen.

8:01 Meine Einschätzung: Für die meisten Teams ist der Umstieg unkritisch, weil sie die neuen Felder zunächst gar nicht brauchen. Die Versionsnummer anzuheben kostet nichts — solange die Kette mitspielt. Und genau das prüft man vorher, nicht nachher. Der rote Faden ist bewusst konservativ: erst prüfen, dann anheben, dann erst neue Felder.

8:21 Der zweite Schritt ist der eigentliche Umstieg und besteht aus einer geänderten Zeile — der Bestand bleibt unangetastet. Erst danach führen Sie einzeln ein, was Ihnen nützt. Der vierte Schritt ist die Rückfallebene für die Praxis: Wenn ein Werkzeug hinterherhinkt, erzeugen Sie ihm eine 3.1-Fassung. Wichtig ist nur, dass diese Fassung erzeugt wird und nicht von Hand gepflegt — sonst haben Sie wieder zwei Wahrheiten.

8:47 Der erste Punkt ist die Reihenfolgeumkehr des eben besprochenen Vorgehens und passiert überraschend oft, weil das Anheben so verlockend einfach ist. Der dritte Punkt ist der teuerste: zwei Fassungen von Hand pflegen. Das funktioniert drei Wochen und driftet dann. Und der vierte ist eine hübsche Praxisfalle — eine Tag-Hierarchie, die tiefer gebaut ist, als die Dokumentationsseite darstellen kann.

9:10 Die Struktur ist dann korrekt und trotzdem unsichtbar. Prüfen Sie das an der Oberfläche, nicht nur am Validator.

Übung

9:17 Jetzt schreiben Sie selbst. Aus dem Ressourcenmodell von gestern wird ein Vertrag — und zwar einer, den ein Werkzeug lesen kann. Wir übersetzen das Ressourcenmodell von gestern in einen Vertrag, den ein Werkzeug lesen kann. Und dann prüfen wir, ob es das auch wirklich tut. Ihre Aufgabe ist, das Lesen und das Anlegen einer Bestellung vollständig zu beschreiben: Parameter, Rumpf, Erfolgsantwort und Fehlerantwort.

9:42 Vollständig heißt hier ausdrücklich, dass die Fehlerfälle aus Modul 4 dazugehören — mit der Problem-Details-Struktur, die Sie gestern entworfen haben. Und diese Struktur beschreiben Sie genau einmal, in components, und verweisen darauf. Als Erweiterung gliedern Sie die Tags über parent und prüfen anschließend, ob Ihre eigene Dokumentationsseite die Hierarchie überhaupt anzeigt.

10:04 Beachten Sie den vierten und fünften Schritt, denn dort liegt der eigentliche Erkenntnisgewinn. Ein Dokument gegen einen Validator laufen zu lassen, ist schnell erledigt und findet erstaunlich viel. Und die Frage, welche Werkzeuge Ihrer Umgebung 3.2 verarbeiten, ist keine akademische — sie entscheidet, ob Sie den Umstieg heute machen können oder noch warten.

10:24 Nehmen Sie die Antwort mit ins eigene Haus; sie ist oft die konkreteste Erkenntnis aus diesem Modul. Der erste Punkt ist der, den ich in dieser Übung am häufigsten sehe: Die Fehlerantwort wird in beide Operationen kopiert, weil das schneller geht als der Verweis. Bei zwei Operationen fällt das nicht auf, bei vierzig schon.

10:44 Der zweite Punkt ist eine Gewohnheitsfrage — im Editor arbeiten ist bequem, aber wenn die Datei dort bleibt, ist sie kein Quelltext. Und der dritte ist die typische Abkürzung unter Zeitdruck: Beispiele weglassen. Am Ende von Modul 8 wissen Sie, warum das teuer wird.