OpenAPI ist ein offener Standard, mit dem sich HTTP-Schnittstellen in einer maschinenlesbaren Datei beschreiben lassen. Die Datei hält fest, welche Endpunkte es gibt, welche Parameter sie erwarten und welche Antworten sie liefern, und ist Grundlage für Dokumentation, Tests und Code.
- OpenAPI
Ein Standard für die Beschreibung von HTTP-Schnittstellen in JSON oder YAML, gepflegt von der OpenAPI Initiative.
Beispiel: „Die OpenAPI-Datei des Zahlungsanbieters haben wir in den Generator gegeben und hatten danach fertige Klassen für alle Aufrufe.“Auch: OpenAPI Specification, kurz OAS. Bis 2016 hieß der Standard Swagger Specification; mehr dazu unter Swagger.
Verwandt: API-Dokumentation, die lesbare Beschreibung, die meist aus einer OpenAPI-Datei entsteht.
Wie eine OpenAPI-Datei aufgebaut ist
Oben stehen Angaben zur Schnittstelle selbst, also Name, Version und Server. Darunter folgt unter paths jeder Pfad mit seinen Methoden, Parametern und möglichen Antworten, und unter components liegen wiederverwendbare Bausteine wie Datenmodelle und Anmeldeverfahren.
openapi: 3.1.0
info:
title: Termine-API
version: 1.0.0
paths:
/termine/{id}:
get:
summary: Einen Termin lesen
responses:
'200':
description: Der Termin als JSONDie Datenmodelle beschreibt OpenAPI seit Version 3.1 mit JSON Schema, demselben Standard, mit dem sich auch andere JSON-Daten prüfen lassen.
Was sich aus OpenAPI erzeugen lässt
Eine lesbare Dokumentation mit Werkzeugen wie Swagger UI, Redoc oder Scalar, Clients in vielen Programmiersprachen, Gerüste für den Server, Testfälle und Mock-Server, die so antworten, als gäbe es die Schnittstelle schon.
Umgekehrt erzeugen manche Frameworks die Datei aus dem Code, FastAPI etwa aus den Typangaben. Für Laravel gibt es Pakete, die sie aus Routen und Prüfregeln ableiten.
Wer hinter OpenAPI steht
Die OpenAPI Initiative, ein Zusammenschluss unter dem Dach der Linux Foundation. Grundlage war die Swagger Specification, die das Unternehmen SmartBear 2015 in die Initiative eingebracht hat; 2016 bekam sie ihren heutigen Namen.
Weil die Datei maschinenlesbar ist, nutzen auch KI-Agenten sie. Ein Sprachmodell, das die OpenAPI-Beschreibung einer Schnittstelle kennt, kann deren Endpunkte selbst aufrufen.