Wer eine OpenAPI-Spec öffnet, sieht die Versionszeile sofort. Steht dort openapi: "3.0.3" oder openapi: "3.1.0", taucht seit September 2025 die Frage auf, was OpenAPI 3.2 mitbringt und ob sich ein Sprung lohnt.
Drei der neuen Features fallen im Alltag direkt auf, weil sie tatsächliche Pain-Points adressieren. Hierarchische Tags machen Doku-Navigation ohne Vendor Extensions möglich, die QUERY-Methode entkoppelt komplexe Filter von der URL, und Streaming-APIs bekommen erstmals erstklassige Unterstützung. Der Rest ist kleiner, aber an einigen Stellen hilfreich.
OpenAPI 3.2.0 ist seit September 2025 verfügbar und bleibt vollständig backward-kompatibel zu 3.0 und 3.1. Drei Erweiterungen lösen konkrete Pain-Points im Alltag. Hierarchische Tags ersetzen Vendor Extensions wie x-tagGroups, die QUERY-Methode bringt GET mit Body als idempotente Operation, und Streaming wird über Server-Sent Events erstklassig unterstützt. Daneben verbessert sich der OAuth-2.0-Device-Flow, die XML-Modellierung wird präziser, und Multipart-Definitionen werden sauberer.
Was OpenAPI 3.2 mitbringt
OpenAPI 3.2.0 wurde am 18. September 2025 freigegeben. Die Spezifikation bleibt strikt backward-kompatibel zu 3.0 und 3.1. Bestehende Specs validieren weiter ohne Anpassung, bestehendes Tooling muss nicht migriert werden. 3.2-spezifische Konstrukte sind opt-in und werden nur dort sichtbar, wo Teams sie aktiv nutzen.
Sieben Bereiche bringen Erweiterungen oder Klarstellungen mit. Hierarchische Tags machen Dokumentations-Navigation ohne Vendor Extensions möglich. Die QUERY-Methode bringt GET mit Body als offizielle, idempotente Operation. Streaming und Server-Sent Events werden erstklassig modellierbar. Der OAuth-2.0-Device-Authorization-Flow ist offiziell beschreibbar. XML-Modellierung deckt Attributes, nested und mixed content präziser ab. Multipart-Definitionen mit File-Upload plus strukturierten Metadaten werden sauberer. Schließlich werden einige ältere Konstrukte und OAuth-Flows als deprecated markiert. Die folgende Tabelle ordnet die wichtigsten Änderungen nach Praxis-Auswirkung.
| Feature | Praxis-Auswirkung |
|---|---|
| Hierarchische Tags | Microservice-Domains lassen sich ohne x-tagGroups oder x-displayName strukturieren. Tag-Navigation wird tool-portabel. |
| QUERY-Methode | Komplexe Filter-Bodies sind idempotent und cacheable, ohne POST-Workaround. Search- und Reporting-APIs bekommen ein passendes HTTP-Verb. |
| Streaming und SSE | Tooling kann Server-Sent Events generieren und validieren, statt sie als Sonderfall zu behandeln. Doppelpflege gegenüber AsyncAPI fällt weg. |
| OAuth Device Flow | CLI-Tools, IoT-Geräte und Smart-TVs ohne Browser-Eingabe sind offiziell beschreibbar. |
| XML-Verbesserungen | Attributes, nested und mixed content lassen sich ohne Vendor Extensions modellieren. |
| Multipart-Klarstellung | File-Upload mit JSON-Metadata in demselben Request wird sauberer abbildbar. |
| Deprecation-Markierungen | Bestand kann gepflegt werden, ohne 3.2 sofort zu erzwingen. |
Aus Migrations-Sicht ist 3.2 ein leichter Sprung. Wer auf 3.1 ist, kann die Versionszeile im Spec-File auf openapi: "3.2.0" setzen und die Spec validiert weiter. Die neuen Konstrukte werden danach gezielt eingeführt, wo ein konkreter Anwendungsfall vorliegt. Eine Big-Bang-Migration über das gesamte API-Portfolio ist weder nötig noch sinnvoll.
Hierarchische Tags machen Doku-Navigation ohne Vendor Extensions möglich
Tags in OpenAPI dienen seit jeher zur Gruppierung von Operationen. Bis 3.1 sind sie eine flache Liste auf Top-Level-Ebene. Wer eine API mit dreißig Endpunkten in fünf Domänen organisieren wollte, kam ohne Vendor Extensions wie x-tagGroups (Redoc) oder x-displayName (verschiedene Tool-Hersteller) nicht aus.
Das Ergebnis war Tooling-spezifisch und nicht portabel. Eine Spec, die in Redoc sauber gegliedert aussah, fiel in Swagger UI auf eine flache Liste zurück. Teams, die Doku-Generatoren wechseln wollten, mussten die Tag-Struktur jedes Mal neu modellieren.
In 3.2 sind hierarchische Tags Bestandteil des Standards. Tag-Objekte tragen jetzt die Felder parent, summary und kind. Aus diesen Feldern lässt sich verschachtelte Navigation erzeugen, und die Struktur bleibt portabel zwischen Renderern.
tags:
- name: Payments
- name: Cards
- name: Transfers
x-tagGroups:
- name: Banking
tags:
- Payments
- Cards
- Transfers
# Mit OpenAPI 3.2
tags:
- name: Banking
summary: "Banking-Domain"
kind: nav
- name: Payments
parent: Banking
summary: "Zahlungsverkehr"
- name: Cards
parent: Banking
summary: "Kartenoperationen"
- name: Transfers
parent: Banking
summary: "Überweisungen"
Die Praxis-Wirkung ist konkret. Wer eine API für eine Banking-Plattform dokumentiert, kann jetzt Domänen wie Payments, Cards und Transfers unter einem gemeinsamen Banking-Knoten gruppieren. Die Navigation erscheint in Swagger UI, Redoc und Scalar konsistent, ohne dass eine Tool-spezifische Konfiguration nötig wäre.
Für bestehende Specs entsteht kein Migrations-Druck. Wer Vendor Extensions weiter nutzt, kann das tun, weil 3.2 die Extensions weiterhin akzeptiert. Wer auf das 3.2-native Pattern umstellt, gewinnt Portabilität und kann die Vendor Extensions schrittweise entfernen.
Die QUERY-Methode bringt GET mit Body als idempotente Operation
GET-Requests sind in der HTTP-Spezifikation für Lesezugriffe vorgesehen, idempotent und cacheable. Sobald die Filter-Logik komplex wird, stößt das Pattern an Grenzen. Lange URLs mit dutzenden Query-Parametern sind unhandlich, und manche Server begrenzen die URL-Länge auf 8 KB oder weniger.
Die naheliegende Lösung war bisher POST mit JSON-Body. Das funktioniert technisch, signalisiert aber falsche Semantik. POST steht für nicht-idempotente Schreiboperationen, ist nicht cacheable und passt damit schlecht zu reinen Lesezugriffen mit komplexen Filtern.
OpenAPI 3.2 unterstützt offiziell die QUERY-Methode. QUERY ist ein laufender HTTP-Standardisierungsversuch durch die IETF und kombiniert die Semantik von GET (idempotent, sicher, cacheable) mit der Möglichkeit, einen Request-Body mitzugeben.
/customers:
query:
summary: Kundensuche mit komplexen Filtern
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
filters:
type: array
items:
$ref: '#/components/schemas/Filter'
sort:
type: array
items:
type: string
responses:
'200':
description: Gefundene Kunden
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerList'
Die Methode ist relevant für Search-APIs, Reporting-Endpunkte und GraphQL-ähnliche Filterstrukturen, in denen die Filter-Logik nicht mehr in Query-Parameter passt. Wer eine Such-API mit zwanzig optionalen Filtern und drei Sortier-Kriterien beschreibt, kann das Modell jetzt sauber abbilden.
Der Tooling-Status ist allerdings noch limitiert. Die meisten HTTP-Clients, Browser-Implementierungen und API-Gateways unterstützen QUERY noch nicht durchgehend. Wer die Methode in der Spec verwendet, denkt heute primär dokumentarisch und greift für die Laufzeit auf POST mit Idempotency-Header zurück, bis das Tooling nachzieht.
Die HTTP-Standardisierung selbst läuft weiter. QUERY ist als IETF-Draft im Status draft-ietf-httpbis-safe-method-w-body aktiv und wird voraussichtlich 2026 oder 2027 als RFC verabschiedet. OpenAPI 3.2 nimmt damit eine Standardisierung vorweg, die im HTTP-Stack selbst noch nicht abgeschlossen ist. Für Teams mit Bestand an POST-basierten Such-APIs lohnt sich eine schrittweise Anpassung der Spec, sobald Client-Bibliotheken im eigenen Stack QUERY unterstützen.
Streaming und Server-Sent Events als first-class
Streaming-APIs ließen sich in OpenAPI bisher schlecht abbilden. Server-Sent Events, Long-Polling und Chunked-Transfer-Endpunkte ließen sich technisch beschreiben, aber das Tooling hatte keine Handhabe, daraus generierten Code zu erzeugen oder die Spec zu validieren. SSE-Endpunkte wurden in der Praxis entweder als reguläre GET-Endpunkte mit text/event-stream deklariert oder ganz aus der Hauptspec ausgelagert.
In 3.2 sind Streaming-Patterns offiziell beschreibbar. Server-Sent Events lassen sich über den Content-Type text/event-stream sauber modellieren, und der Streaming-Charakter eines Endpunkts wird Tooling-lesbar. In der Spec wird damit zwischen einmaligen Responses und kontinuierlichen Event-Streams unterschieden. In Beispielen wird zusätzlich häufig eine Vendor-Extension wie x-stream: true ergänzt, solange Generatoren das offizielle Streaming-Feld noch nicht breit unterstützen.
/events:
get:
summary: Event-Stream über Server-Sent Events
responses:
'200':
description: Kontinuierlicher Event-Stream mit Order-Updates
content:
text/event-stream:
schema:
$ref: '#/components/schemas/OrderEvent'
x-stream: true
Tooling-Implementierungen wie OpenAPI Generator und Spectral arbeiten an Support für die Streaming-Marker. Bis dahin bleibt der konkrete Mehrwert auf Dokumentation und Validierung beschränkt, was für viele Teams aber bereits den Hauptnutzen ausmacht.
Wir haben Streaming-APIs vor 3.2 in einer eigenen AsyncAPI-Spezifikation parallel zur OpenAPI-Spec geführt. Der Doppel-Pflegeaufwand fiel weg, sobald 3.2 produktiv war und die SSE-Endpunkte direkt im OpenAPI-Dokument beschreibbar wurden. Die Konsumenten der Spec mussten nicht mehr zwei verschiedene Tools im Kopf haben, je nachdem, ob sie einen synchronen oder einen Stream-Endpunkt aufrufen wollten.
Die Abgrenzung zu AsyncAPI bleibt bestehen. AsyncAPI deckt komplexe Event-Driven-Architekturen mit Pub-Sub-Patterns, Channel-Definitionen und Message-Brokern ab. OpenAPI 3.2 mit Streaming-Support deckt synchrone und semi-synchrone HTTP-basierte Streaming-Patterns ab, in denen ein Server kontinuierlich Daten an einen Client sendet.
Typische Anwendungsfälle für Streaming in OpenAPI 3.2 sind Live-Order-Updates in E-Commerce-Plattformen, Telemetrie-Streams aus IoT-Geräten, Progress-Updates bei lang laufenden Backend-Tasks und Live-Notifications in Banking- oder Logistik-Anwendungen. Wer einen dieser Anwendungsfälle abbildet und bisher mit Workarounds gearbeitet hat, gewinnt durch 3.2 spürbar an Klarheit in der Spec.
Weitere Änderungen, die seltener auffallen
Die kleineren Erweiterungen in 3.2 fallen weniger auf, helfen aber spezifischen Anwendungsfällen, die in 3.1 nur schwer beschreibbar waren.
- OAuth-2.0-Device-Authorization-Flow. Der Flow nach RFC 8628 ist jetzt offiziell als Flow-Variante in der Spec verfügbar. Er adressiert CLI-Tools, IoT-Geräte und Smart-TVs ohne Browser-Eingabe, in denen ein Code an einer Console eingegeben wird, während die eigentliche Authentifizierung an einem zweiten Gerät stattfindet. Vor 3.2 musste der Flow über Vendor Extensions oder als generischer Custom-Flow modelliert werden.
- XML-Modellierung. Attributes, nested elements und mixed content lassen sich ohne Workarounds beschreiben. Für Bestände in Versicherungs-, Healthcare- oder Logistik-APIs, die XML-basierte Schnittstellen weiter pflegen, ist das eine echte Verbesserung. Wer XML als Bestandsformat für SAP-Integrationen oder EDI-Anbindungen führt, gewinnt sauberere Spec-Beschreibungen.
- Multipart-Definitionen. Die Kombination aus File-Upload und strukturierten JSON-Metadaten in demselben Request wird sauberer abbildbar. Wer einen Endpunkt für Bild-Uploads mit Beschreibungs-Metadaten oder Dokumenten-Uploads mit Klassifizierungs-JSON beschreibt, kommt ohne erklärende Kommentare in der Spec aus.
- Deprecation-Markierungen. Einige ältere Konstrukte sind als deprecated markiert. Die
nullable: true-Modellierung aus 3.0 wird offiziell zugunsten der JSON-Schema-konformen Variante aus 3.1 abgelöst, einige OAuth-Flow-Varianten gelten als veraltet, und Konventionen rund umconsumesundproducesaus dem 2.0-Erbe werden abschließend zurückgewiesen. Die Deprecation-Markierungen beziehen sich auf Stilfragen, nicht auf Validität. Bestand bleibt validierbar, aber Linter werden zunehmend Warnungen ausgeben.
Wann sich der Sprung von 3.1 zu 3.2 lohnt
Die Entscheidung pro oder contra 3.2 ist im Vergleich zu früheren Versions-Sprüngen ungewöhnlich klar. 3.2 ist backward-kompatibel zu 3.1, und der Migrations-Aufwand bleibt minimal. Welche Features konkret gebraucht werden, entscheidet die Antwort.
- Streaming oder Server-Sent Events im Anwendungsfall. Der Sprung lohnt sich. Tooling-Generation und Validation für SSE-Endpunkte werden möglich, statt Workarounds zu pflegen.
- Hierarchische Doku-Navigation gewünscht. Der Sprung lohnt sich. Vendor Extensions wie
x-tagGroupskönnen entfernt werden, die Spec wird tool-portabel. - Komplexe Filter-Endpunkte (Search, GraphQL-ähnliche Filter). Der Sprung lohnt sich. QUERY entkoppelt Filter-Body von Query-Parameter-Limits, sauberer als POST mit Idempotency-Header.
- Keiner der drei Treiber konkret. Kein akuter Migrations-Druck. 3.1 bleibt valide, der Sprung kann später erfolgen, wenn ein Use-Case auftaucht.
Der Tooling-Status ist beim Sprung der zweite Faktor. OpenAPI Generator, Spectral und die großen Doku-Renderer wie Swagger UI, Redoc und Scalar haben 3.2-Support unterschiedlich umgesetzt. Wer Auto-Generation aus der Spec macht, prüft die 3.2-Unterstützung im konkreten Stack zuerst, bevor produktive Specs umgestellt werden.
Migrations-seitig ist der Sprung von 3.1 zu 3.2 reine Schema-Anpassung. Bestehende tags-Strukturen, Path-Definitionen und Component-Schemas bleiben gültig. 3.2-Konstrukte werden ergänzt, nicht ersetzt, und Tooling, das 3.2 nicht versteht, ignoriert die neuen Felder still. Wer die Spec mit einem 3.1-Linter validiert, bekommt höchstens Warnungen für unbekannte Felder, keine Fehler. Wer dagegen aus Swagger 2.0 kommt, findet den Format-Sprung in einem eigenen Migrations-Guide nach OpenAPI 3.x.
Wie api-portal.io OpenAPI 3.2 unterstützt
In api-portal.io werden OpenAPI 3.2 sowie 3.0 und 3.1 parallel unterstützt. Beim Spec-Import werden 3.2-Konstrukte wie hierarchische Tags, QUERY-Operations und Streaming-Marker direkt erkannt und in der Dokumentations-Oberfläche dargestellt. Der API Linter prüft 3.2-spezifische Patterns gegen denselben Style Guide, der auch für 3.0 und 3.1 gilt.
Der API Explorer unterstützt die Darstellung mehrerer API-Formate.