OpenAPI und Swagger

Eine Einführung in OpenAPI und Swagger

Erik Seifried | HTL Leonding

Einführung: Was ist eine API?

Der Vertrag zwischen zwei Systemen:

Eine API (Application Programming Interface) ist wie ein Vertrag zwischen 2 (oder mehreren) Systemen. Sie legt fest, wie die Systeme miteinander kommunizieren und welche Informationen ausgetauscht werden.

Restaurant Beispiel:

Die API sorgt dafür, dass der Austausch von Informationen standardisiert abläuft.
Das bedeutet, dass die Informationen in einem festgelegten Format JSON oder YAML übermittelt werden.
Im Restaurant-Beispiel könnte man dies mit der Sprache vergleichen, die alle Beteiligten Sprechen (Annahme: Alle sprechen Englisch).

Was ist OpenAPI und welche Alternativen gibt es?

OpenAPI im Überblick:

OpenAPI ist ein Standard zur Beschreibung von Programmierschnittstellen
Früher bekannt als "Swagger"

Alternativen zu OpenAPI (2 Beispiele):

RAML (RESTful API Modeling Language):
RAML wurde 2013 von MuleSoft entwickelt.
YAML-basiert Open Source
Mulesoft: 2006 gegründet, San Francisco, Kalifornien

Beispiel:

RAML

API Blueprint API Blueprint wurde 2013 von Apiary entwickelt.
Markdown-basiert
Open Source

Beispiel: API Blueprint

Welches Problem löst OpenAPI?

Wenn man eine REST-API hat kann niemand zu diesem Server hingehen und fragen: "Was kannst du eigentlich?".

Welche Endpunkte gibt es?
Welche HTTP-Methoden (GET, POST, PUT, DELETE) kann ich nutzen?
Welche Datenformate (JSOn, XML) werden erwartet?
Welche Parameter werden benötigt (Query-Parameter, Path-Parameter, Body)?
Welche Antwort bekomme ich zurück?

Genau dieses Problem löst OpenAPI:

Schnittstllendokumentation mit der Swagger UI

Swagger UI ermöglicht es die API-Ressourcen zu visualisieren und mit ihnen zu interagieren.
Implementierungslogik muss nicht vorhanden sein
Dokumentation kann automatisch aus der OpenAPI-Spezifikation (YAML-File) generiert werden