🌳Aufbau einer OpenAPI-Datei

Eine OpenAPI-Beschreibung ist ein einziges verschachteltes Objekt. Oben stehen Metadaten, darunter die Pfade mit ihren Operationen und am Ende die wiederverwendbaren Bausteine. Klicken Sie sich durch die Buchladen-API.

🗺️Das Grundgerüst

OpenAPI Object
├── openapi: 3.1.1           ← Pflicht: Version der SPEZIFIKATION
├── info                     ← Pflicht: title, version (der API)
├── servers[]                ← Basis-URLs
├── paths                    ← Endpunkte
│   └── /books/{bookId}      ← Path Item
│       ├── parameters[]     ← gilt für alle Methoden
│       ├── get              ← Operation
│       │   ├── operationId
│       │   ├── parameters[] ← path · query · header · cookie
│       │   ├── requestBody  ← content → Media Type → schema
│       │   ├── responses    ← '200', '404', default …
│       │   └── security     ← überschreibt global
│       └── delete …
├── webhooks                 ← ab 3.1
├── components               ← wiederverwendbar per $ref
│   ├── schemas · parameters · responses
│   ├── requestBodies · headers · examples
│   └── securitySchemes
├── security[]               ← globale Anmeldung
└── tags[]                   ← Gruppen für die Doku

HTTP-Anfrage                         OpenAPI
─────────────────────────────────    ───────────────────────────────
DELETE                           →   paths./books/{bookId}.delete
https://api.example.org/v1       →   servers[0].url
/books/42                        →   Pfad-Template + in: path
?force=true                      →   parameters (in: query)
Authorization: Bearer eyJ…       →   security → securitySchemes
Content-Type: application/json   →   requestBody.content-Schlüssel
{ … }                            →   requestBody … schema

HTTP-Antwort
─────────────────────────────────    ───────────────────────────────
204 No Content                   →   responses.'204'
404 + application/problem+json   →   responses.'404' → $ref

💡 Zwei Versionen – nicht verwechseln

openapi: 3.1.1 nennt die Version der Spezifikation. info.version: 1.2.0 ist die Version Ihrer API-Beschreibung. In YAML immer als Text schreiben – unquotiert würde 3.1 als Zahl gelesen.

🌲Interaktiver Baum

Punkte zeigen die Objektart (Farbe), ein Klick klappt auf und erklärt. Violette $ref-Chips springen zum Ziel des Verweises.

Buchladen-API · openapi.yaml

openapi: "3.1.1"Pflicht

▾infoPflicht

title: "Buchladen-API"Pflicht

summary: "Bücher suchen, anlegen und bestellen"

description: "Beispiel-API der App VisualOpenApi – all…"

version: "1.2.0"Pflicht

▸license{ 2 }

▸servers[ 2 ]

▸tags[ 2 ]

▸security[ 1 ]

▾paths

▸/books{ 2 }

▸/books/bestseller{ 1 }

▾/books/{bookId}

▸parameters[ 1 ]

▾GET

operationId: "getBook"

▸tags[ 1 ]

summary: "Ein Buch lesen"

▸security[ 0 ]

▾responses

▾200

description: "Das Buch"

▸content{ 1 }

404

▸DELETE{ 5 }

▸/orders{ 1 }

▸webhooks{ 1 }

▾components

▸schemas{ 6 }

▸parameters{ 2 }

▸responses{ 3 }

▸securitySchemes{ 3 }

Response › content › application/json › schema

#/paths/~1books~1{bookId}/get/responses/200/content/application~1json/schema

Inhalt einer Antwort: je Media Type ein Schema und Beispiele.

$ref-Auflösung

#/paths/~1books~1{bookId}/get/responses/200/content/application~1json/schema
↳ #/components/schemas/Book

{
  "description": "Ein Buch im Katalog (NewBook plus Server-Felder)",
  "allOf": [
    {
      "$ref": "#/components/schemas/NewBook"
    },
    {
      "type": "object",
      "required": [
        "id"
      ],
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64",
          "minimum": 1,
          "readOnly": true
        }
      }
    }
  ]
}

Der Verweis wird wie ein Link auf eine andere Stelle desselben Dokuments gelesen: „#“ = dieses Dokument, danach ein JSON-Pointer (RFC 6901), in dem „/“ im Schlüssel als „~1“ geschrieben wird.

🔗$ref-Auflösung Schritt für Schritt

Ein $ref ist eine URI: vor dem „#“ steht das Dokument, danach ein JSON-Pointer. Der Parser geht Segment für Segment durch das Dokument – probieren Sie auch den Tippfehler „Bok“ und den externen Verweis.

Eigener Verweis

Schritt 1 / 7 · Tasten ← →

ℹ️ Verweis lesen
$ref: '#/components/schemas/Book'
✅ Dokument bestimmen
✅ JSON-Pointer zerlegen
✅ Schritt 1: „components“
✅ Schritt 2: „schemas“
✅ Schritt 3: „Book“
✅ Ziel erreicht

Aktuelle Position im Dokument

🕸️ Verweis-Graph der Buchladen-API (24 Verweise)

Links die Fundstellen, rechts die Ziele. Fahren Sie über ein Ziel, um zu sehen, wer es benutzt – so sieht man, was eine Änderung an einer Komponente alles betrifft.

🔁 Zyklus gefunden: Category → Category – erlaubt (rekursive Daten wie Kategoriebäume), aber Werkzeuge dürfen solche Verweise nicht blind „inline“ auflösen. Der Resolver dieser App setzt an der Stelle eine Markierung { $circular: … }.

🕰️Swagger 2.0 → OpenAPI 3.0 → 3.1 → 3.2

Die wichtigsten Unterschiede. Grün = neu in dieser Version. Der größte Schritt für Schemas war 3.1: seitdem ist ein Schema Object reines JSON Schema 2020-12.

Thema	Swagger 2.0	OpenAPI 3.0	OpenAPI 3.1	OpenAPI 3.2
Kennung	swagger: "2.0"	openapi: 3.0.x	openapi: 3.1.x	openapi: 3.2.x
Server	host + basePath + schemes	servers[] mit Variablen	wie 3.0	+ name je Server
Request-Body	Parameter in: body / formData	requestBody.content je Media Type	wie 3.0	+ itemSchema (Streaming), in: querystring
Wiederverwendung	definitions, parameters, responses, securityDefinitions	components (schemas, responses, parameters, examples, requestBodies, headers, securitySchemes, links, callbacks)	+ components.pathItems	+ components.mediaTypes
Schemas	Teilmenge von JSON Schema Draft 4	erweiterte Teilmenge (Draft Wright-00) + nullable	vollständig JSON Schema 2020-12: type-Arrays, const, examples[], $defs; nullable entfällt	wie 3.1 (eigener Dialekt 3.2)
$ref mit Nachbarfeldern	werden ignoriert	werden ignoriert	Schema: erlaubt · Reference Object: summary/description	wie 3.1
Pflicht auf oberster Ebene	paths	paths	mind. eines: paths, components, webhooks	wie 3.1
Operation.responses	Pflicht	Pflicht	optional	optional
Response.description	Pflicht	Pflicht	Pflicht	optional, + summary
Webhooks	–	nur callbacks	webhooks (oberste Ebene)	wie 3.1
HTTP-Methoden	get put post delete options head patch	+ trace	wie 3.0	+ query, additionalOperations
Security	basic, apiKey, oauth2	http (basic, bearer …), apiKey, oauth2, openIdConnect	+ mutualTLS	+ OAuth2 deviceAuthorization, oauth2MetadataUrl, deprecated
Tags	name, description, externalDocs	wie 2.0	wie 3.0	+ summary, parent, kind (Hierarchie)
Info / License	license: name, url	wie 2.0	+ info.summary, license.identifier (SPDX)	wie 3.1
Dokument-Basis	–	–	jsonSchemaDialect	+ $self (eigene URI)

vorher (3.0)

# OpenAPI 3.0 – eigenes Schlüsselwort
subtitle:
  type: string
  nullable: true

nachher (3.1)

# OpenAPI 3.1 / 3.2 – reines JSON Schema 2020-12
subtitle:
  type: [string, 'null']