English
Agenten-Protokolle

OpenAPI

OpenAPI ist ein herstellerneutrales, sprachunabhängiges Format zur Beschreibung von HTTP-APIs. Eine OpenAPI-Beschreibung legt in JSON oder YAML fest, welche Endpunkte eine API hat, welche Parameter sie erwartet und was sie zurückgibt. Menschen und Programme können die API dadurch verstehen, ohne den Quellcode zu kennen. Der Begriff „Open API“ wird außerdem für öffentlich zugängliche Schnittstellen verwendet. Dieser Eintrag behandelt die Spezifikation.

Auf einen Blick

Herausgeber
OpenAPI Initiative (Linux Foundation)
Verbindet
HTTP-APIs mit Entwicklern und Werkzeugen über eine maschinenlesbare Beschreibung
Status
Spezifikation der OpenAPI Initiative, aktuelle Version 3.2.1 (10.09.2026)
Lizenz
Apache 2.0
Spezifikation
OpenAPI Specification

Stand:

Wie ist OpenAPI aufgebaut?

Die OpenAPI Specification (OAS) beschreibt eine API als Dokument mit mehreren Bereichen. Das Info-Objekt enthält Metadaten wie Titel und Version. Das Paths-Objekt listet die Endpunkte und ihre Operationen auf. Wiederverwendbare Bausteine wie Schemas, Parameter und Antworten liegen im Components-Objekt. Dazu kommen Angaben zu Servern und zur Absicherung.

Gepflegt wird die Spezifikation von der OpenAPI Initiative, die unter dem Dach der Linux Foundation arbeitet. Sie geht auf die Swagger Specification zurück, die SmartBear gespendet hat.

Wofür wird OpenAPI genutzt?

Die OpenAPI Initiative nennt mehrere Einsatzzwecke: API-Dokumentation, die automatische Erzeugung von Client- und Servercode, Testautomatisierung und die Konfiguration von API-Gateways. Da das Format maschinenlesbar ist, können Werkzeuge die Beschreibung direkt weiterverarbeiten.

Für die Auffindbarkeit von APIs definiert RFC 9727 den Pfad /.well-known/api-catalog. Dort kann ein Betreiber ein maschinenlesbares Verzeichnis seiner APIs mit Metadaten ablegen. Cloudflare prüft diesen API-Katalog im Agent Readiness Score.

Beispiel

Das Beispiel verwendet zur Illustration die Version 3.1.0. Die aktuelle Version laut spec.openapis.org ist 3.2.1.

YAML
openapi: 3.1.0
info:
  title: Beispiel-API
  version: "1.0"
paths:
  /seiten/{id}:
    get:
      summary: Eine Seite abrufen
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Die Seite wurde gefunden.

Häufige Fehler

  • Das Feld openapi weglassen. Es ist Pflicht und muss die Versionsnummer der verwendeten Spezifikation enthalten.
  • Die Einstiegsdatei beliebig benennen. Die Spezifikation empfiehlt openapi.json oder openapi.yaml, damit Werkzeuge und Menschen sie finden.
  • YAML-Parser mit abweichender Version nutzen. Die Spezifikation empfiehlt YAML 1.2, damit JSON und YAML sich verlustfrei ineinander überführen lassen.

Häufige Fragen

Was ist der Unterschied zwischen OpenAPI und Swagger? Swagger war die Vorgängerspezifikation. Die OpenAPI Specification baut auf ihr auf und wird heute von der OpenAPI Initiative weiterentwickelt.

Welche Formate sind erlaubt? Eine OpenAPI-Beschreibung kann als JSON oder als YAML geschrieben werden. Beide Formate sind gleichwertig.

Quellen

  1. What is OpenAPI? – OpenAPI Initiativeopenapis.org
  2. About the OpenAPI Initiativeopenapis.org
  3. OpenAPI Specification (latest) – spec.openapis.orgspec.openapis.org
  4. RFC 9727: api-catalog – IETFrfc-editor.org

Stand: