Veröffentlichen Sie ein OpenAPI-(Swagger-)Dokument für die REST-API Ihrer App in Jitterbit App Builder

Einführung

Ein OpenAPI-(Swagger-)Dokument ist eine standardisierte, maschinenlesbare Beschreibung einer REST-API, die durch die OpenAPI-Spezifikation definiert wird. Seit App Builder 4.67 können Sie ein OpenAPI-(Swagger-)Dokument veröffentlichen, das die REST-API Ihrer App beschreibt, im JSON- oder YAML-Format. Jedes Tool, das OpenAPI unterstützt – ob andere Anwendungen der Harmony-Plattform (wie API Manager) oder externe Tools von Drittanbietern – kann dieses Dokument ohne Authentifizierung abrufen, um die verfügbaren Endpunkte Ihrer Anwendung, deren Parameter und die erforderliche Authentifizierungsmethode automatisch zu ermitteln. Diese Seite beschreibt, wie man dieses Dokument veröffentlicht, wo es verfügbar ist, was es enthält und wie Authentifizierungsmethoden zugeordnet werden. Am Ende finden Sie eine Liste der aktuellen bekannten Probleme und Einschränkungen.

App Builder kann auch die umgekehrte Operation ausführen, d. h. ein externes OpenAPI-Dokument nutzen, um einen REST-Endpunkt zu erstellen. Weitere Informationen finden Sie unter Importieren Sie ein OpenAPI-(Swagger-)Dokument, um einen Endpunkt zu erstellen.

Veröffentlichen Sie ein OpenAPI-Dokument

App Builder veröffentlicht standardmäßig kein OpenAPI-Dokument für die APIs Ihrer Anwendung. Bevor Sie ein Dokument veröffentlichen können, müssen Sie die App bereits als REST-API-Endpunkt veröffentlicht haben. Führen Sie diese Schritte aus, um ein OpenAPI-Dokument zu veröffentlichen:

1. Gehen Sie zu IDE > REST APIs.

2. Suchen Sie die Anwendung, für die Sie ein OpenAPI-Dokument veröffentlichen möchten, und klicken Sie auf das Chevron-Symbol auf ihrer Kachel. Die Seite REST API für diese API wird geöffnet.

   Wenn Ihre Anwendung nicht aufgelistet ist, haben Sie sie noch nicht als REST-API-Endpunkt veröffentlicht.

3. Klicken Sie im Bereich Service auf Edit.

4. Aktivieren Sie die Option Publish Documentation. Dies teilt App Builder mit, dass das OpenAPI-Dokument generiert und veröffentlicht werden soll.

5. Geben Sie optional eine Summary und eine Description an.

6. Klicken Sie auf Save.

Standardmäßig bezieht App Builder alle Ressourcen der API in das OpenAPI-Dokument ein, es sei denn, Sie wählen Ressourcen aus, die ausgeschlossen werden sollen.

Schließen Sie eine Ressource aus der API-Dokumentation aus

Wenn Sie eine einzelne Ressource aus der generierten OpenAPI-Dokumentation ausschließen möchten, wird dies auch auf der Seite REST API der API konfiguriert:

1. Gehen Sie zu IDE > REST APIs.

2. Suchen Sie die Anwendung, für die Sie ein OpenAPI-Dokument veröffentlichen möchten, und klicken Sie auf das Chevron-Symbol auf ihrer Kachel. Die Seite REST API für diese API wird geöffnet.

   Wenn Ihre Anwendung nicht aufgelistet ist, haben Sie sie noch nicht als REST-API-Endpunkt veröffentlicht.

3. Suchen Sie im Bereich Resources die Ressource, die Sie aus der Dokumentation ausschließen möchten, und klicken Sie auf das Detailsymbol. Die Seite REST Resource für diese Ressource wird geöffnet.

4. Klicken Sie im Bereich Resource auf Edit.

5. Aktivieren Sie die Option Exclude From Documentation. Dies schließt diese Ressource aus dem generierten Dokument aus, auch wenn Publish Documentation für die REST-API insgesamt aktiviert ist.

6. Klicken Sie auf Save.

Details zum OpenAPI-Dokument

In diesem Abschnitt werden die Details des OpenAPI-Dokuments beschrieben, das App Builder für die REST-APIs Ihrer Anwendung veröffentlichen kann.

Dokument-URL

Nach der Veröffentlichung ist das OpenAPI-Dokument unter der gleichen Basis-URL wie Ihre App-REST-API verfügbar, mit openapi.json oder openapi.yaml angehängt:

.../rest/v1/{endpoint}/openapi.json
.../rest/v1/{endpoint}/openapi.yaml

Ersetzen Sie {endpoint} durch den REST-API-Endpunkt, der für Ihre Anwendung konfiguriert ist (z. B. northwinds).

Dokumentinhalt

Das generierte OpenAPI-Dokument spiegelt die REST-API wider, die von der Anwendung bereitgestellt wird:

• Jede veröffentlichte Ressource, einschließlich aller untergeordneten Knoten, wird zu einem path im Dokument.

• Geschäftsobjektspalten und -eigenschaften werden zu Feldern im entsprechenden components/schemas-Modell, wobei ihre App-Builder-Datentypen OpenAPI-Datentypen zugeordnet werden.

• Eingabeparameter werden zu OpenAPI-Pfad- oder Abfrageparametern.

• Nur benutzerdefinierte Ereignisse, die für REST-Zugriff ausgewählt wurden, werden einbezogen und verwenden ihren konfigurierten URL-freundlichen Namen.

Authentifizierungszuordnung

Das generierte Dokument deklariert ein Sicherheitsschema in components/securitySchemes für jede Authentifizierungsmethode, die auf den Endpunkten der Anwendung konfiguriert ist:

Bekannte Probleme und Einschränkungen

Das generierte Dokument unterliegt denselben bekannten Problemen und Einschränkungen wie die zugrunde liegende REST-API.