🧩 Visuelle Erklärung · Stand 24.09.2026: OpenAPI 3.2.1

OpenAPI – der Vertrag zwischen API und Client

OpenAPI (bis 2015 „Swagger“) beschreibt eine HTTP-API maschinenlesbar in einer YAML- oder JSON-Datei: welche Pfade es gibt, welche Parameter und Bodies erlaubt sind, welche Antworten kommen und wie man sich anmeldet. Aus dieser einen Datei entstehen Dokumentation, Client-Code, Mock-Server und Tests.

🌳 Aufbau erkunden ✍️ Eigene Spezifikation prüfen

openapi: 3.1.1
info:
  title: Buchladen-API
  version: 1.2.0
paths:
  /books/{bookId}:
    get:
      operationId: getBook
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Book'

🔗Eine Datei, viele Nutznießer

Die OpenAPI-Beschreibung (OAD, OpenAPI Description) ist die gemeinsame Quelle. Fahren Sie über die Kästen – jede Kante zeigt, was ein Werkzeug aus der Datei macht.

Aus der Spezifikation wird …

📦 Client-SDKs

openapi-generator, Orval

Erzeugt typisierte Clients (TypeScript, Java, Python …) – Tippfehler in Pfaden fallen beim Kompilieren auf.

🗓️Von Swagger zu OpenAPI 3.2

Versionsdaten aus dem Anhang „Revision History“ der Spezifikation, geprüft am 24.09.2026 auf spec.openapis.org. Aktuell: 3.2.1 (Linie 3.2), 3.1.2 (3.1) und 3.0.4 (3.0).

1.0
10.08.2011
Erste Swagger-Spezifikation
1.2
14.03.2014
Erstes formales Dokument
2.0
08.09.2014
Swagger 2.0 – eine Datei, JSON/YAML
2.0
31.12.2015
Übergabe an die OpenAPI Initiative (Linux Foundation)
3.0.0
26.07.2017
Umbenennung zu OpenAPI, components, requestBody, servers
3.1.0
15.02.2021
Voll kompatibel mit JSON Schema 2020-12, webhooks
3.0.4 / 3.1.1
24.10.2024
Patch-Releases (Klarstellungen)
3.2.0
19.09.2025
QUERY, Tag-Hierarchie, Streaming, $self, Device-Flow
3.1.2
19.09.2025
Patch-Release
3.2.1
10.09.2026
Patch-Release – aktuellste Version

🧭Kapitel

🌳

Aufbau einer OpenAPI-Datei

Interaktiver Baum: openapi, info, servers, paths, Operationen, components – und wie $ref aufgelöst wird.

✍️

Editor + Live-Vorschau

YAML oder JSON links, selbst gebaute Doku rechts. Validierung mit verständlichen deutschen Meldungen.

🔬

Request-Debugger

Eine HTTP-Anfrage in 8 Schritten gegen die Spezifikation prüfen: Pfad, Methode, Security, Parameter, Body.

⚙️

Code & Werkzeuge

TypeScript-Typen, fetch-Client und curl aus der Spezifikation; Generatoren, Mock-Server, Linter.

🔐

Security-Schemes

API-Key, Basic, Bearer, OAuth2-Flows und OpenID Connect – als Ablauf und als HTTP-Header.

🧭

Praxis

Versionierung, Best Practices, häufige Fehler und Abgrenzung zu AsyncAPI, GraphQL, JSON:API, MCP.

❓Swagger oder OpenAPI?

📜 OpenAPI Specification

Der offene Standard der OpenAPI Initiative (Linux Foundation). Versionen ab 3.0 heißen „OpenAPI“.

🛠️ Swagger

Heute der Markenname einer Werkzeugfamilie (Swagger UI, Swagger Editor, Swagger Codegen). Die Spezifikation bis 2.0 hieß ebenfalls Swagger.

🧾 OAD

„OpenAPI Description“ – so nennt die Spezifikation eine konkrete Beschreibung (eine oder mehrere Dateien), z. B. openapi.yaml.