Einführung in die API-Spezifikation So verwenden Sie den Swagger Editor

Ossi Galkin avatarGeschrieben vonOssi Galkin Vor über einer Woche aktualisiertTable of contents

So verwenden Sie den Swagger Editor

Swagger Editor ist das Tool, das zum Erstellen der API-Spezifikationen verwendet wird. Die API-Spezifikation definiert, wie die API funktioniert. Frends unterstützt die Formate Swagger 2.0 und OpenAPI 3.0 im Swagger Editor. Es wird jedoch dringend empfohlen, das OpenAPI 3.0-Format zu verwenden, da es vielseitiger ist als das ältere Swagger 2.0.

Um mit der API-Erstellung zu beginnen, müssen wir zunächst zur API-Ansicht in Frends navigieren. Stellen Sie sicher, dass Ihr Frends-Benutzer über die erforderlichen Zugriffsrechte verfügt, indem Sie überprüfen, ob die Registerkarte „API-Ansicht“ im Frends-Kontrollfeld angezeigt wird.

In der API-Ansicht sind alle vorgefertigten API-Spezifikationen aufgelistet. Beginnen wir mit der Erstellung, indem wir auf die Schaltfläche „Neu erstellen“ klicken. Dadurch wird der Swagger-Editor mit einer bereits als Vorlage für Sie erstellten Beispiel-API geöffnet.

Auf der linken Seite der Ansicht sehen Sie den Swagger-Editor. Die Vorlagenspezifikation ist standardmäßig im OpenAPI 3.0.1-Format. Wie im vorherigen Modul erwähnt, unterstützt Frends sowohl OpenAPI 3.0 als auch Swagger 2.0, es wird jedoch empfohlen, das neuere OpenAPI 3.0-Format zu verwenden. Die eigentliche Spezifikation ist in der Sprache YAML geschrieben. Weitere Informationen zu YAML finden Sie hierLernprogramm. Sie können die Spezifikation auch in JSON konvertieren, indem Sie auf die Schaltfläche „In JSON konvertieren“ klicken, wenn Ihnen das lieber ist. Wenn Sie die Spezifikation bereits mit einem anderen Tool erstellt haben, können Sie die YAML- oder JSON-Spezifikation direkt in den Swagger Editor kopieren und einfügen.

Auf der rechten Seite sehen Sie die API-Definitionen, die vom Swagger Editor gesammelt werden. Die Definitionen werden automatisch aktualisiert, wenn Änderungen am Swagger Editor vorgenommen werden. Alle im Editor definierten Endpunkte (Pfade) werden erstellt und Sie können sie prüfen, indem Sie auf den Endpunkt klicken. Hier sehen Sie erforderliche Parameter und mögliche Antworten, die in der Spezifikation definiert sind. Sie können Ihre APIs auch mit den API-Definitionen testen, nachdem Sie die erste Version der API-Spezifikation gespeichert haben.

Während Sie Änderungen an den API-Spezifikationen vornehmen, hebt der Swagger Editor etwaige Fehler in der Spezifikation hervor und benachrichtigt Sie darüber. Im Bild unten fehlt beispielsweise nach der Schemazeile ein Doppelpunkt.

Um Ihre Spezifikation abzuschließen, klicken Sie unten auf der Seite auf die Schaltfläche „Änderungen speichern“.

Dadurch gelangen Sie zurück zur API-Ansicht und können Ihre neu erstellte API-Spezifikation in der Liste sehen.

Nachdem die Spezifikation abgeschlossen ist, müssen Sie die eigentlichen Funktionen für die API implementieren. Dies geschieht durch die Erstellung verknüpfter Prozesse, die die eigentlichen Funktionen der API handhaben. Sie können einen verknüpften Prozess erstellen, indem Sie unter dem Endpunkt auf „Neuen Prozess erstellen“ klicken. Mehr über diese verknüpften Prozesse erfahren Sie im Kurs L3C5 „Implementieren von Endpunkten“.

Der nächste Artikel istEinführung in die Implementierung von Endpunkten.


Verwandte ArtikelSchreiben einer API-Spezifikation in Frends: Teil 1Einführung in „Was ist zum Erstellen einer API erforderlich?“Einführung in den Prozess der API-Erstellung und Erstellen einer API-SpezifikationEinführung in die OpenAPI-SpezifikationEinführung in OpenAPI 2.0 und OpenAPI 3.0