APIs spielen eine entscheidende Rolle in der heutigen vernetzten Welt. Fast jede App auf deinem mobilen Gerät wird von einer API unterstützt. Aus diesem Grund ist die API-Entwicklung heutzutage ein trendiges Thema geworden. Es gibt viele Standards, die im Bereich der API-Entwicklung populär geworden sind. Einer dieser Standards ist das Format von API-Spezifikationsdokumenten. Die OpenAPI-Spezifikation (früher bekannt als Swagger) hat sich als das De-facto-Format zur Beschreibung von APIs in der modernen API-Welt etabliert. Es gibt auch viele großartige Tools, die darum herum entwickelt wurden, um die API-Entwicklung und das API-Lifecycle-Management zu erleichtern. In diesem Artikel werden wir die Bedeutung der OpenAPI-Spezifikation und drei großartige OpenAPI-Tools diskutieren, die deinen API-Entwicklungszyklus produktiv und effizient machen können.
Der herausforderndste Aspekt der API-Entwicklung
Es gibt zwei Hauptakteure im API-Ökosystem: die API-Anbieter und die API-Nutzer. Der API-Anbieter stellt eine API bereit und der API-Nutzer konsumiert sie. Die API selbst ist jedoch nicht das Einzige, was der API-Anbieter dem API-Nutzer zur Verfügung stellt. Es gibt auch andere verwandte Produkte wie API-Dokumentationen, SDKs, Postman-Sammlungen usw. Jedes Mal, wenn sich etwas in der API ändert, muss der API-Anbieter auch all diese verwandten Produkte aktualisieren. Es kann sehr schwierig sein, all diese Änderungen manuell zu verfolgen und entsprechend zu aktualisieren. Andererseits, wenn du viele APIs besitzt, kann das manuelle Aktualisieren all dieser Produkte auch nicht skalierbar sein. Was wäre, wenn du einen Weg hättest, diesen Prozess zu automatisieren? Was wäre, wenn jedes Mal, wenn du deine API änderst, all die oben genannten nachgelagerten Produkte automatisch aktualisiert werden? Klingt erstaunlich, nicht wahr? Das ist tatsächlich möglich. Alles, was du brauchst, ist eine Quelle der Wahrheit für deine API. Hier kommen OpenAPI-Dateien (oder OAS-Definitionen) ins Spiel.
Wie OpenAPI-Dateien den Tag retten können
Was bedeutet es, dass OpenAPI-Dateien die Quelle der Wahrheit deiner API sein können? Das ist einfach. Du beginnst deine API einfach mit einer OpenAPI-Datei. Das nennt man „API-First-Entwicklung“. Sobald deine OpenAPI-Datei bereit ist, generierst du alles andere daraus. Es gibt viele Tools, die API-Dokumentationen, SDKs, Postman-Sammlungen usw. aus OpenAPI-Dateien generieren können. Aber was ist mit der eigentlichen Implementierung? Die gute Nachricht ist, dass du sogar die API-Implementierung teilweise generieren kannst. Grundsätzlich generierst du das Gerüst deiner API-Implementierung. Wenn du ein Java-Entwickler bist, generierst du ein paar Java-Schnittstellen und eine Reihe von Modellklassen. Dann musst du nur noch diese Schnittstellen implementieren. Das bedeutet, dass dein Code-Basis zwei Arten von Code enthält: generierten Code und manuell geschriebenen Code. Was ist mit den Änderungen? Wenn du eine Änderung an deinem API-Vertrag vornehmen möchtest, machst du dies in der OpenAPI-Datei und generierst deinen Code erneut. Es ersetzt den generierten Code, berührt aber deinen manuell geschriebenen Code nicht. Du musst möglicherweise einige manuell geschriebene Code-Teile aktualisieren, um den neu generierten Änderungen zu entsprechen. Das war’s. So funktioniert der API-First-Ansatz.
OpenAPI-Tools, die dir das Leben erleichtern
Es gibt viele großartige Tools, die verschiedene Aspekte von OpenAPI-Dateien abdecken. Dazu gehören Tools, die Code generieren, Dokumentationen erstellen, SDKs generieren, Tests erstellen usw. Solche Tools sind in der Regel sehr beliebt, da sie sehr häufige Anwendungsfälle abdecken. Du kannst leicht viele Informationen über solche Tools im Internet finden. Daher werden wir nicht über diejenigen sprechen, die die häufigsten Anwendungsfälle abdecken. Stattdessen werden wir über drei großartige OpenAPI-Tools sprechen, die nicht so populär sind, aber für den API-Entwicklungszyklus unerlässlich sein können.
Spectral: OpenAPI Linter Tool
Wir haben besprochen, wie der API-First-Ansatz das Leben für API-Entwickler erleichtert. Das Definieren und Aktualisieren von OpenAPI-Dateien kann jedoch aufgrund möglicher syntaktischer und semantischer Fehler sehr schwierig sein, es sei denn, wir haben einen geeigneten Validierungsmechanismus, der jede OpenAPI-Datei, die wir schreiben und aktualisieren, validieren kann. Hier kommt das Spectral Linter Tool ins Spiel.
Spectral ist ein Open-Source-Linter-Tool für OpenAPI-Dateien. Es hat eine Reihe von eingebauten Regeln, um die Gültigkeit von OpenAPI-Dateien sicherzustellen. Dieses Standardregelwerk repräsentiert die OpenAPI-Spezifikation (OAS), die definiert, was eine OpenAPI-Datei ist, wie sie aussehen sollte, was sie tun kann, wie sie erweitert werden kann usw. Darüber hinaus kannst du auch deine eigenen benutzerdefinierten Spectral-Regeln definieren, um zusätzliche Regeln zu validieren, die du durchsetzen möchtest, z.B. die internen REST API Designrichtlinien deines Unternehmens.
Hier sind einige Standardregeln, die im täglichen API-Entwicklungsprozess sehr nützlich sind.
- API-Endpunkte sollten nicht mehrdeutig sein, was bedeutet, dass es keine mehrfach überlappenden API-Endpunkte geben sollte.
- OpenAPI-Dateien sollten „Server“ definiert haben.
- API-Anfrage- und Antwort-Payload-Beispiele, die in einer OpenAPI-Datei angegeben sind, sind gemäß den in der OpenAPI-Datei definierten API-Modellen gültig.
- Gegebene Beispiele sollten mit mindestens einem der API-Endpunkte verknüpft sein.
Wie bereits erwähnt, kannst du zusätzlich zu den Standardregeln auch deine eigenen benutzerdefinierten Regeln definieren. Zum Beispiel kann es organisationsspezifische API-Richtlinien geben, die du für die APIs deiner Organisation durchsetzen möchtest. Hier sind einige Beispiele.
- Pfadparameter, Abfrageparameter usw. sollten im Camel-Case-Format sein.
- Jedes Anfrage- und Antwortmodell sollte Beispiele haben.
- Jeder API-Endpunkt sollte ein oder mehrere Sicherheitsmechanismen zugewiesen haben.
- Enum-Werte sollten nicht dupliziert sein.
Hier ist, wie du eine benutzerdefinierte Spectral-Regel definieren kannst. Diese benutzerdefinierte Regel besagt, dass APIs immer eine Beschreibung in ihrem Info-Objekt definiert haben müssen.
rules:
info-description:
given: $.info
then:
field: description
function: truthy
Zusätzlich zu der Definition eigener Regeln kannst du auch die Standardregeln ändern. Eine Möglichkeit, dies zu tun, besteht darin, den Schweregrad der Standardregeln zu ändern. Zum Beispiel kannst du eine Standardregel auf „Fehler“-Ebene in „Warnung“ ändern. Oder du kannst die Standardregeln sogar komplett deaktivieren.
Spectral ermöglicht es dir, eine Hierarchie von Regeldateien zu definieren, bei der eine Regeldatei von einer anderen überschrieben werden kann. In diesem Artikel werden wir dies nicht im Detail besprechen. Es wird bald einen separaten Artikel nur über Spectral geben, der tief in seine Funktionen eintaucht.
Hier sind einige wichtige Links zu Spectral:
Spectral unterstützt die OpenAPI-Spezifikationen v2.0, v3.0 und v3.1.
Wenn du ein Benutzer des WSO2 API Managers bist, gibt es gute Nachrichten für dich. WSO2 API Manager unterstützt Spectral jetzt ab APIM 4.2.0 standardmäßig.
OpenAPI Diff Tool
Das OpenAPI-Diff-Tool ist ein weiteres großartiges Open-Source-OpenAPI-Tool. Es ermöglicht dir, den Unterschied zwischen zwei APIs zu sehen. Dies ist besonders wichtig, wenn du den Unterschied zwischen zwei Versionen (oder Revisionen) derselben API sehen möchtest.
Das OpenAPI-Diff-Tool ist als CLI sowie als Java-Bibliothek verfügbar. Wenn du das Tool ausführst, musst du lediglich die beiden Eingabe-OpenAPI-Dateien angeben, zwischen denen du den Unterschied sehen möchtest, und dann gibt es dir den Unterschied in einem übersichtlichen Format aus. Du kannst auch das Ausgabeformat auswählen. Es unterstützt HTML, JSON und Markdown (.md).
Hier ist ein Beispiel für die Verwendung der CLI, die anweist, den Unterschied zwischen den Dateien newsapi_v5.yaml und newsapi_v6.yaml zu generieren und in einer Datei namens newsapi_diff_v5_v6.md im Markdown-Format zu speichern.
openapi-diff /specs/newsapi_v5.yaml /specs/newsapi_v6.yaml --markdown /output/newsapi_diff_v5_v6.md
Die Ausgabe enthält hauptsächlich die folgenden Abschnitte:
- Neue Endpunkte
- Gelöschte Endpunkte
- Veraltete Endpunkte
- Geänderte Endpunkte
- Geänderte Erweiterungen
- Geänderte Elemente
- Brechende (nicht abwärtskompatible) Änderungen
- Nicht brechende (abwärtskompatible) Änderungen
Lassen Sie uns nun einige praktische Anwendungsfälle des Diff-Tools besprechen.
Als API-Entwickler, wenn du eine neue Version deiner API veröffentlichen möchtest, musst du möglicherweise auch Versionshinweise vorbereiten. Und du musst möglicherweise auch eine „Neuigkeiten“-Seite vorbereiten. In diesen Dokumenten musst du API-Vertragsänderungen sowie funktionale Änderungen der API einschließen. Das OpenAPI-Diff-Tool kann sehr hilfreich sein, um alle Vertragsänderungen zu generieren, die du in der neuen API-Version hast.
Ein weiterer wichtiger Anwendungsfall des OpenAPI-Diff-Tools ergibt sich aus seiner Fähigkeit, brechende Änderungen zu erkennen. Wenn du kleinere Versionen deiner API veröffentlichst, musst du sicherstellen, dass sie keine brechenden (nicht abwärtskompatiblen) Änderungen einführen. Andernfalls können deine Client-Integrationen/Anwendungen kaputtgehen, was du um jeden Preis vermeiden musst. Daher kann ein Tool im API-Entwicklungsprozess zur frühzeitigen Erkennung von brechenden API-Änderungen das Leben erleichtern. Das OpenAPI-Diff-Tool ist intelligent genug, um zu erkennen, ob eine erkannte Änderung eine brechende Änderung ist oder nicht. Das CLI-Tool hat die eingebaute Option „–fail-on-incompatible“ für diesen Zweck.
Während das CLI-Tool sehr einfach zu verwenden ist, kannst du mit der Java-Bibliothek des Tools noch benutzerdefiniertere Dinge tun, indem du seine Fähigkeiten erweiterst. Ob du das CLI-Tool oder die Java-Bibliothek verwenden solltest, sollte davon abhängen, ob du Einfachheit oder Flexibilität bevorzugst.
Hier sind einige wichtige Links zum OpenAPI-Diff-Tool:
Laut offizieller Dokumentation unterstützt das OpenAPI-Diff-Tool nur die OpenAPI-Spezifikation v3.0. Laut einigen Diskussionen in seinem Git-Repo könnte es jedoch in seinem aktuellen Zustand auch die OpenAPI v3.1-Version unterstützen, auch wenn dies nicht direkt in den offiziellen Dokumenten behauptet wird.
OpenAPI Merge Tool
Dies ist ein weiteres großartiges OpenAPI-Tool, das dir die Möglichkeit gibt, mehrere OpenAPI-Dateien in eine zu mergen. Dieses Tool ist nützlich, wenn mehrere Teams verwandte APIs (z.B. Microservices) entwickeln und du diese gemeinsam den Nutzern zur Verfügung stellen möchtest.
Die Aufgabe des OpenAPI-Merge-Tools ist sehr einfach. Es benötigt zwei oder mehr OpenAPI-Dateien als Eingaben und mergen sie einfach zu einer einzigen OpenAPI-Datei. Im Gegensatz zu den beiden zuvor besprochenen Tools benötigt das OpenAPI-Merge-Tool jedoch eine Konfigurationsdatei, die die Pfade zu Eingabe- und Ausgabedateien definiert. Hier ist eine Beispielkonfigurationsdatei.
Manchmal kann das Mergen von OpenAPI-Dateien kompliziert sein, da die angegebenen Eingabedateien die gleichen oder ähnlichen Ressourcen und Modelle haben können. Das Mergen solcher Dateien kann zu Merge-Konflikten führen. Das OpenAPI-Merge-Tool behandelt solche Konflikte auf zwei Arten:
- Wenn beide OpenAPI-Dateien das gleiche Modell-Schema haben, werden sie als dasselbe behandelt, und nur eines davon wird in die Ausgabedatei kopiert. Dann wird dies von den anderen Komponenten, die aus beiden Eingabedateien kopiert wurden, referenziert.
- Wenn der Schemaname derselbe ist, aber ihre Eigenschaften in zwei Eingabedateien unterschiedlich sind, können sie nicht als dasselbe Modell behandelt werden. In diesem Fall sollten beide Modelle in die Ausgabedatei aufgenommen werden, aber sie können nicht denselben Namen haben. Dies erfordert die Umbenennung eines der konfliktierenden Modell-Schemanamen. In solchen Fällen benötigt das Tool Hilfe von einem Fachexperten, wie dem API-Entwickler, um zu entscheiden, welche OpenAPI-Datei Vorrang haben soll. Das Tool erwartet daher, dass der Entwickler dem Tool mitteilt, dass Modelle welcher Eingabe-OpenAPI-Dateien bei einem Konflikt umbenannt werden sollen und wie sie umbenannt werden sollen. Das Gute daran ist, dass dies im Voraus in der Konfigurationsdatei des Tools konfiguriert werden kann. Du kannst Komponenten konfigurieren, welche Eingabe-OpenAPI-Dateien umbenannt werden sollen und mit welchem Präfix oder Suffix. Hier ist eine Beispielkonfiguration.
Das ist nur eine Hauptfunktion dieses Tools. Hier sind einige weitere wichtige Funktionen:
- Präfixe und Suffixe können zu den angegebenen OpenAPI-Dateien hinzugefügt werden, unabhängig von Konflikten.
- Endpunkte können basierend auf ihren Tags ausgewählt oder entfernt werden.
- Pfadmodifikationen können durch Entfernen und Hinzufügen von Teilen durchgeführt werden.
- OpenAPI-Datei-Info-Beschreibungen können zusammengeführt werden oder eine komplett neue Beschreibung kann in der zusammengeführten Ausgabedatei festgelegt werden.
Hier sind einige wichtige Links zum OpenAPI-Merge-Tool:
Derzeit unterstützt das OpenAPI-Merge-Tool nur die OpenAPI-Spezifikation v3.0. Die Unterstützung für OpenAPI v3.1 steht noch aus.
Fazit
In diesem Artikel haben wir die Bedeutung von OpenAPI-Dateien für den API-Entwicklungszyklus und wie OpenAPI-Tools eine bessere und einfachere Nutzung von OpenAPI-Dateien ermöglichen, besprochen. Am wichtigsten ist, dass in diesem Artikel drei großartige OpenAPI-Tools vorgestellt wurden: das Spectral Linter Tool, das OpenAPI-Diff-Tool und das OpenAPI-Merge-Tool. Wir haben besprochen, welche Probleme jedes dieser Tools löst, wie man sie verwendet und was ihre Hauptfunktionen sind. Wenn du also ein API-Entwickler, ein Produktmanager oder jemand bist, der in der API-Entwicklung arbeitet, könnte dieser Artikel eine wertvolle Ressource sein. Jetzt geh und probiere diese ausgezeichneten Tools aus: Es wird sich auf lange Sicht in deiner API-Reise auszahlen.