OpenAPI-Unterstützung im REST-Schritt

  • Freigeben Version: Yokohama
  • Aktualisiert 30. Januar 2025
  • 3 Minuten Lesedauer

    • Füllen Sie REST-Schrittfelder und Aktionseingaben mit aus einer OpenAPI-Spezifikation importierten Informationen aus. Importieren Sie Spezifikationen, indem Sie eine URL für YAML oder JSON bereitstellen oder Inhalte kopieren und einfügen.

    Vorteile

    OpenAPI-Unterstützung im REST-Schritt bietet diese Vorteile.

    • Verwenden Sie Informationen, die aus einer OpenAPI-Spezifikation importiert wurden, um REST-Schrittvorgänge, HTTP-Methoden, Parameter, Anforderungstext, Pfad und Header zu konfigurieren.
    • Überprüfen Sie verfügbare API-Vorgänge, ohne die Flow Designer-Schnittstelle zu verlassen.
    • Generieren Sie Eingaben, die für den REST-Schritt erforderlich sind, um gültige Anforderungen an einen OpenAPI-Service zu senden, und fügen Sie sie dem REST-Schritt an der richtigen Stelle hinzu.
    Hinweis:
    Überprüfen Sie vor dem Senden einer Anforderung immer die aus einer OpenAPI-Spezifikation importierten REST-Schrittwerte. Entfernen Sie Parameter, Header und Eingaben, die die API nicht benötigt.

    Generierte Eingaben

    Wenn Sie eine OpenAPI-Spezifikation importieren, erstellt das System die erforderlichen Eingaben und fügt sie gegebenenfalls dem REST-Schrittformular hinzu. Zur Laufzeit sendet das System eine REST-Anforderung, die Eingabewerte enthält, die für die Aktion bereitgestellt werden. Wenn für eine API beispielsweise die Übergabe eines Namensparameters in der Anforderung erforderlich ist, erstellt das System eine Namenseingabe und fügt sie dem REST-Schritt hinzu. Wenn Sie die Aktion dem Flow hinzufügen, wird der Name zu einer Eingabe für die Aktion.

    Das System ordnet OpenAPI-Datentypen den Datentypen Workflow-Studio zu. Wenn beispielsweise die OpenAPI-Spezifikation ein Benutzerobjekt erfordert, erstellt das System ein komplexes Datenobjekt als Eingabe. Weitere Informationen finden Sie unter Komplexe Daten.

    Größenbeschränkung für Spezifikation

    Standardmäßig kann das System OpenAPI-Spezifikationen mit bis zu 10 MB importieren. Um die Importgröße zu erhöhen, aktualisieren Sie die Systemeigenschaft glide.rest.openapi.max_request_size. Der Höchstwert beträgt 100 MB.

    Spezifikationsverwaltung

    Importieren Sie eine OpenAPI-Spezifikation, indem Sie im REST-Schritt Optionen auswählen. Weitere Informationen finden Sie unter REST-Schritt. Durch das Importieren einer OpenAPI-Spezifikation wird ein Datensatz in der Tabelle „OpenAPIs“ [sys_openapi] erstellt. Sie können Spezifikationsdatensätze direkt in dieser Tabelle anzeigen oder löschen. Um eine Spezifikation zu aktualisieren, löschen Sie sie, und importieren Sie sie erneut.

    Design Überlegungen

    Beachten Sie beim Erstellen eines REST-Schritts aus einer OpenAPI-Spezifikation die folgenden Überlegungen.

    Entfernen Sie unnötige REST-Schrittparameter
    Beim Importieren einer OpenAPI-Spezifikation fügt das System dem REST-Schritt alle in der Spezifikation enthaltenen Parameter und Header hinzu. Überprüfen Sie die endgültigen REST-Schrittwerte, und entfernen Sie Parameter, die Sie in der Anforderung nicht senden möchten. Wenn die API beispielsweise Inhaltstypheader für JSON und XML akzeptiert, fügt das System beide Header dem REST-Schritt hinzu. Entfernen Sie je nach Inhaltstyp, den Sie in der Antwort erhalten möchten, einen der Header.
    Machen Sie Eingabebezeichnungen anwenderfreundlich
    Stellen Sie sicher, dass für den REST-Schritt erforderliche Eingabebezeichnungen klar und verständlich sind. Eindeutige Bezeichnungen ermöglichen es Flow Designern, die erforderlichen Eingaben leicht zu verstehen, wenn sie die Aktion in einem Flow verwenden.
    Entfernen Sie Eingaben, für die keine Flow Designer-Konfiguration erforderlich ist
    Beim Importieren einer OpenAPI-Spezifikation fügt das System alle in der Spezifikation vorhandenen Eingaben dem Aktionseingabeabschnitt hinzu. Entfernen Sie alle Eingaben, für die kein Flow Designer konfiguriert werden muss. Wenn beispielsweise eine REST-Schrittvariable einen Wert von einem anderen Schritt in der Aktion erhält, ist keine Aktionseingabe erforderlich.
    Vermeiden Sie es, den API-Vorgang zu ändern
    Durch Ändern des Werts des Felds „API-Vorgang“ werden alle von diesem Vorgang abhängigen Werte entfernt. Wenn Sie die OpenAPI-Spezifikationswerte im REST-Schrittformular konfigurieren und dann den Vorgang ändern, speichert das System Ihre Konfiguration nicht. Werte, die manuell von einem Benutzer eingegeben werden, sind nicht betroffen.

    Einschränkungen

    Erstellen Sie einen REST-Schritt aus einer OpenAPI-Spezifikation mit diesen Einschränkungen.

    Medientypen des Anforderungstexts
    Der Anforderungstext unterstützt nur JSON- und XML-basierte Medientypen. Wenn der ausgewählte Vorgang aus der importierten OpenAPI-Spezifikation einen Anforderungstext mit einem anderen Medientyp enthält, fügt das System dem Feld Anforderungstext eine Datenpille vom Typ „Zeichenfolge“ hinzu.
    OpenAPI 3.0-Komponenten

    OpenAPI 3.0 fügt zu „Swaiger 2.0“ neue Komponenten hinzu, um eine API detaillierter zu beschreiben. Die OpenAPI-Unterstützung im REST-Schritt unterstützt einige, aber nicht alle dieser Komponenten. Der REST-Schritt unterstützt diese Komponenten derzeit nicht.

    • Schemaobjekt: Eigenschaften „oneOf“, „anyOf“.
    • Unterscheidungsmerkmalobjekt
    • Info-Objekt: „termsOfService“, „Kontakt“, „Lizenz“-Felder
    • Beispielobjekt
    • Link-Objekt
    • Rückrufobjekt
    • Sicherheitsschemaobjekt
    • Sicherheitsanforderungsobjekt
    • Tag-Objekt
    • Externes Dokumentationsobjekt
    • Serverobjekt
    • Spezifikationserweiterungen
    • Rekursive Verweise

    Weitere Informationen zu diesen Komponenten finden Sie in der OpenAPI-Dokumentation. Siehe OpenAPI-Spezifikation.