Generieren Sie Prozesse aus OpenAPI-Spezifikationen (Swagger).
Geschrieben vonOssi Galkin Vor über einer Woche aktualisiertTable of contentsFrends unterstützt das Importieren und Bearbeiten von Swagger-Spezifikationen. Swagger-Spezifikationen können zum Generieren von Prozessen verwendet werden, die als API-Endpunkte dienen. Prozesse, die zu einer Spezifikation gehören, können als Einheit verwaltet und bereitgestellt werden.
 |
|
Die API-Verwaltungsseite finden Sie unter „API“.
Importieren einer Swagger-Definition
Frends unterstützt den Import der Swagger 2.0-Spezifikation im JSON-Format. YAML-Markup wird nicht unterstützt. Wenn Ihre Swagger-Spezifikation im YAML-Format vorliegt, verwenden Sie beispielsweise dieOnline-Swagger-Editorum eine konvertierte Version herunterzuladen. Dieses Tool kann auch zum Erstellen von Swagger-Spezifikationen verwendet werden, die in Frends importiert werden können.
Es ist möglich, eine importierte Swagger-Spezifikation mit externen Tools zu ändern. Wenn Sie eine importierte Swagger-Spezifikation aktualisieren möchten, importieren Sie einfach die aktualisierte Spezifikation und Frends erstellt automatisch eine neue Version der Spezifikation. Beachten Sie, dass sich zwischen den Importen der Basispfad der Spezifikation nicht ändern kann. Wenn der Basispfad abweicht, wird eine neue API erstellt und nicht eine neue Version der alten API.
API-Bereitstellung und Versionskontrolle
API-Versionen gibt es in zwei verschiedenen Zuständen. Die Version, die in der Entwicklungsumgebung angezeigt wird, ist immer die aktuelle Entwicklungsversion einer API. In allen anderen Umgebungen werden veröffentlichte Versionen angezeigt.
Entwicklungsversionen
Eine Entwicklungsversion einer API ist eine Version, bei der die verknüpften Prozesse keine gesperrten Versionen haben. Das bedeutet, dass der Benutzer jeden Prozess, der Teil der API ist, aktualisieren kann, ohne zusätzliche Aktionen ausführen zu müssen. Die Swagger-Spezifikation der Entwicklungsversion kann auch geändert werden. Wenn eine API zur Bereitstellung bereit ist, wird eine veröffentlichte Version erstellt.
Veröffentlichte Versionen
Eine veröffentlichte Version enthält alles, was eine Entwicklungsversion tut, lässt aber keine Änderungen mehr zu. Sie sperrt die verwendeten Prozessversionen und die Swagger-Spezifikation kann nicht mehr geändert werden. Eine veröffentlichte Version kann als Einheit bereitgestellt werden und kann auch verwendet werden, um die Entwicklungsversion auf einen früheren Punkt zurückzusetzen.
Bereitstellen
Beim Bereitstellen kann der Benutzer wählen, ob er eine zuvor veröffentlichte Version bereitstellen oder eine neue veröffentlichte Version aus der aktuellen Entwicklungsversion erstellen möchte. Im Bereitstellungsdialog kann der Benutzer sehen, welche Prozesse bereitgestellt werden, sowie die Swagger-Spezifikation. Wenn eine veröffentlichte Version nicht mehr gültig ist, beispielsweise weil ein verwendeter Prozess gelöscht wurde, kann sie nicht mehr bereitgestellt werden.
Swagger bearbeiten
Frends unterstützt das Bearbeiten importierter Swagger-Spezifikationen. Der Basispfad einer Swagger-Spezifikation kann nach dem Import nicht mehr geändert werden.
Beachten Sie, dass das Bearbeiten einer Swagger-Spezifikation die aktuelle Swagger-Spezifikation überschreibt und standardmäßig keinen Rollback-Punkt erstellt. Wenn Sie vor dem Bearbeiten einen Rollback-Punkt wünschen, drücken Sie auf Bereitstellung und wählen Sie „Speichern und bereitstellen“. Dadurch wird eine neue Version der Spezifikation erstellt und Sie können zu einem späteren Zeitpunkt ein Rollback durchführen. Es ist nicht zwingend erforderlich, den Bereitstellungsschritt durchzuführen.
Erstellen von API-Prozessen
Sobald eine Swagger-Spezifikation importiert wurde, können Frends Prozesse erstellen, die den in der Spezifikation definierten API-Operationen entsprechen.
Ein aus einer API-Spezifikation generierter Prozess enthält eineAPI-Trigger. Der Trigger gibt dem Prozess Zugriff auf alle erwarteten Variablen, die an den Endpunkt übergeben werden, und wandelt sie sogar in den richtigen Typ um.
Ein generierter Prozess wird auch mit vorgenerierten Antworten geliefert. Wenn beispielsweise ein Endpunkt so definiert ist, dass er bei Erfolg ein Pet-Objekt und andernfalls ein Error-Objekt zurückgibt, enthält der Prozess bei der Erstellung beide Antworten, vollständig mit den erwarteten Parametern (sofern die Swagger-Spezifikation natürlich alle erforderlichen Informationen enthält). Was zwischen dem Auslöser und den Antworten passiert, liegt im Ermessen des Benutzers.
Beachten Sie, dass einige der in der Swagger-Spezifikation definierten Einstellungen auf Prozessebene festgelegt werden. Unterstützte Schemata sowie die Authentifizierung werden vom API-Trigger festgelegt und können von den in der Spezifikation definierten Einstellungen abweichen.
Sobald die API erstellt ist, kann der Basispfad nicht mehr bearbeitet werden, da alle Betriebs-URIs darauf basieren. Wenn mehrere Versionen benötigt werden, kann dem Basispfad eine Versionsnummer hinzugefügt werden. Der Vorteil unterschiedlicher Basispfade für v1 und v2 der APIs besteht beispielsweise darin, dass Sie beide in derselben Umgebung bereitstellen können.
FRENDS fügt beim Speichern „api“ zum Basispfad hinzu, beispielsweise.beispiel.com/API/foo/bar/v3,wenn es das nicht schon hat. Das Präfix /api ist dafür da, dass Sie auch einfache HTTP-Trigger haben können. Die API-Trigger haben ihr eigenes reserviertes Präfix, sodass es keine Routenkonflikte gibt, z. B. mit HTTP-Trigger mit Route /foo/bar und API-Trigger /api/foo/bar
Aufheben der Verknüpfung eines Prozesses
Ein Prozess, der aus einer API-Operation erstellt wurde, ist mit der API-Spezifikation verknüpft, die ihn erstellt hat. Das bedeutet, dass der Prozess bereitgestellt wird, wenn die API bereitgestellt wird, und die API-Bereitstellung stellt sicher, dass die richtige Version dieses Prozesses bereitgestellt wird.
Wenn Sie die Verknüpfung eines Prozesses mit einer API aufheben möchten, um beispielsweise einen neuen Prozess für diese API-Operation zu erstellen, klicken Sie einfach auf „Prozessverknüpfung aufheben“. Ein aufgehobener Prozess kann problemlos erneut mit einer API verknüpft werden.
Bei Swagger-Operation geändert
Frends erkennt, wenn sich eine Swagger-Operation für einen Prozess mit einem API-Trigger geändert hat. Dies kann beim Importieren einer neuen Version einer Spezifikation oder beim Bearbeiten der Swagger-Spezifikation passieren – beispielsweise kann eine Operation einen zusätzlichen Parameter erhalten oder es gibt eine Änderung der Schemadefinition.
Frends bietet die Funktion, den API-Trigger des Prozesses zu aktualisieren, damit er der neuen Swagger-Spezifikation entspricht. Beachten Sie, dass dadurch nur der Trigger aktualisiert wird. Wenn sich die erwarteten Antworten geändert haben, liegt es am Benutzer, diese zu ändern.
HTTP-Antworttypen
Antworten werden in einer Swagger-Operation durch HTTP-Statuscodes definiert. Für Codes, die mit 2 oder 3 beginnen (Erfolg / Umleitung), wird ein ReturnElementwird generiert. Für andere wird ein Throw-Element generiert.
Beachten Sie, dass das Verhalten dieser beiden Elemente unterschiedlich ist.
Ein Throw-Element beendet den Prozess in einem Fehlerzustand. Wenn es in einem Bereich oder einer Schleife verwendet wird, beendet es die Prozessausführung, ohne fortzufahren. Throw führt auch dazu, dass Fehlerhandler ausgelöst werden.
Eine Rückgabe beendet den Prozess in einem Erfolgszustand und wird bei Verwendung in einem Bereich oder einer Schleife weiterhin ausgeführt.
Wenn Sie eine Fehlerantwort senden müssen, aber nicht das Verhalten eines Throw-Elements wünschen, fügen Sie einfach ein Return-Element mit denselben Einstellungen wie das Throw-Element hinzu.
Löschen von API-Spezifikationen
Beim Löschen aus einer Nicht-Entwicklungsumgebung werden nur die bereitgestellten Prozesse und die bereitgestellte API-Spezifikation entfernt. Diese bleiben in der Entwicklungsumgebung bestehen und können von dort aus erneut bereitgestellt werden. Beim Löschen aus der Entwicklungsumgebung werden die API sowie die verknüpften Prozesse entfernt. Das Löschen der API aus der Entwicklungsumgebung ist nur möglich, wenn sie nicht in anderen Umgebungen bereitgestellt ist.
Swagger-Funktionen werden nicht unterstützt
Formularparameter werden nicht unterstützt.
Dateiparameter werden nicht unterstützt.
Für die automatische Vervollständigung im Prozesseditor stehen nur auf Operationsebene definierte Parameter zur Verfügung.
API-Erkennung
Aktive Prozesse, die Teil einer API-Spezifikation sind, können auf der Seite „Agent API Discovery“ gefunden, untersucht und getestet werden. Durch Navigieren zu https://<Agent-URL>:<Port>/api/docs/ wird eine Liste aktiver Spezifikationen angezeigt. Durch Navigieren zu einer Spezifikation kann jeder aktive Vorgang untersucht und getestet werden.
Verwandte ArtikelErstellen einer Frends-APIZugriff auf die Verwaltungs-API mit Swagger UIEinführung in die Bereitstellung von APIs und die API-VersionskontrolleBeispiel für die Bereitstellung der aktuellen Entwicklungsversion einer APIManagement-API v.0.9 Endpunkte