Artikel: OpenAPI Technologie
Spezifikation, Dokumentation und Code-Generierung mit OpenAPI
Das OpenAPI Dokument ist Spezifikation und Dokumentation von API Schnittstellen und Antwortstrukturen zugleich.
Spezifikation herunterladen
Die Spezifikation kann aus dem DB API Marketplace wie folgt heruntergeladen werden.
- API Baustein im DB API Marketplace aufrufen.
- API Spezifikation wählen.
- Link OpenAPI-Dokument herunterladen anklicken.
Spezifikation visualisieren
Die Visualisierung kann mit zahlreichen marktüblichen Tools erfolgen. Exemplarisch zeigen wir den Weg mit dem Swagger Editor, alternativ können aber auch Tools wie zum Beispiel Redocly eingesetzt werden.
- Spezifikation aus dem DB API Marketplace herunterladen.
- Swagger Editor aufrufen und die Spezifikation hochladen.
- Die verschiedenen Funktionalitäten können, gruppiert nach der spezifischen Domäne, der Übersicht entnommen werden.
- Pro Funktionalität werden die Anfrageparameter aufgeführt und ausführlich beschrieben. Ein * kennzeichnet Pflichtparameter.
- Die Antwortstrukturen werden im Bereich Responses gleichermaßen ausführlich beschrieben.
Code-Generierung
Die OpenAPI Spezifikation kann zur automatisierten Code-Generierung für eine große Anzahl von Programmiersprachen und Frameworks verwendet werden. Damit können selbst für umfangreiche Antwortstrukturen in wenigen Minuten Clients automatisiert erzeugt und im folgenden direkt verwendet werden.
Zur Code-Generierung empfehlen wir den OpenAPI-Generator und verweisen auf dessen umfangreiche Dokumentation mit zahlreichen Beispielen. Am Beispiel der Programmiersprache Java lässt sich ein Client für den API Baustein RIS::Journeys z.B. wie folgt generieren:
java -jar openapi-generator-cli-7.3.0.jar
generate -g java
--additional-properties=library=native,useJakartaEe=true,openApiNullable=false
--api-package de.db.risapi.client.journeys.api
--invoker-package de.db.risapi.client.journeys.invoker
--model-package de.db.risapi.client.journeys.model
-i <PATH_TO_YOUR_SPEC>
Der so erstellte Api-Client kann dann z.B. wie nachfolgend beschrieben initialisiert werden:
final ApiClient oClient = new ApiClient();
oClient.updateBaseUri("<BASE_URI>");
oApiClient.setConnectTimeout(Duration.ofMillis(<CONNECTION_TIMEOUT>));
oClient.setRequestInterceptor(new Consumer<HttpRequest.Builder>() {
public void accept(HttpRequest.Builder builder) {
builder.header("DB-Client-Id", "<SECRET>");
builder.header("DB-Api-Key", "<SECRET>");
builder.timeout(Duration.ofMillis(<REQUEST_TIMEOUT>));
}
});
Basierend auf unseren Erfahrungen möchten wir gerne folgende Erkenntnisse teilen:
- Die Qualität des generierten Quellcodes hängt stark von der Open-Source Community ab, welche die Generatoren betreut. Es ist nahezu immer davon auszugehen, dass generierter Code hier und da noch ein wenig angepasst werden muss.
- Die Automatisierung der Client-Code-Generierung mit gängigen Build-Tools, wie z.B. Maven oder Gradle, lohnt in der Regel nicht. Mit der Zeit, die für eine vollständige Automatisierung aufgewendet werden muss, lassen sich hinreichend viele Clients von Hand generieren.
Authentifizierung und Autorisierung
Um die APIs verwenden zu können, müssen alle Anfragen mit der DB-Client-ID und dem zugehörigen DB-Api-Key authentifiziert werden. Das vorangegangene Code-Beispiel zeigt, wie diese über die HTTP-Header bei jedem Request übergeben werden müssen.
Wie man die Zugangsdaten erhält, und ggf. bei Verlust selbst neue vergeben kann, ist hier beschrieben: So startest Du einfach mit den APIs
Links
- OpenAPI Spezifikation (siehe auch Swagger)
- OpenAPI Generator
- Redocly oder Swagger Editor
Weiter