Veröffentliche ein OpenAPI-(Swagger-)Dokument für die REST-API deiner App in Jitterbit App Builder

Einführung

Ein OpenAPI-(Swagger-)Dokument ist eine standardisierte, maschinenlesbare Beschreibung einer REST-API, die von der OpenAPI-Spezifikation definiert wird. Seit App Builder 4.67 kannst du ein OpenAPI-(Swagger-)Dokument veröffentlichen, das die REST-API deiner App beschreibt, im JSON- oder YAML-Format. Jedes Tool, das OpenAPI unterstützt – ob andere Anwendungen der Harmony-Plattform (wie API Manager) oder externe Drittanbieter-Tools – kann dieses Dokument ohne Authentifizierung abrufen, um die verfügbaren Endpunkte deiner Anwendung, ihre Parameter und die Authentifizierungsmethode, die jeder benötigt, automatisch zu erkennen. Diese Seite beschreibt, wie man dieses Dokument veröffentlicht, wo es verfügbar ist, was es enthält, wie Authentifizierungsmethoden zugeordnet werden und wie man alle veröffentlichten APIs auf deinem App-Builder-Server auflistet. Am Ende findest du eine Liste der aktuellen bekannten Probleme und Einschränkungen.

App Builder kann auch die umgekehrte Operation durchführen; das heißt, ein externes OpenAPI-Dokument konsumieren, um einen REST-Endpunkt zu erstellen. Siehe Importiere ein OpenAPI-(Swagger-)Dokument, um einen Endpunkt zu erstellen, um mehr zu erfahren.

Veröffentliche ein OpenAPI-Dokument

App Builder veröffentlicht standardmäßig kein OpenAPI-Dokument für die APIs deiner Anwendung. Bevor du eines veröffentlichen kannst, musst du die App bereits als REST-API-Endpunkt veröffentlicht haben. Führe diese Schritte aus, um ein OpenAPI-Dokument zu veröffentlichen:

1. Gehe zu IDE > REST APIs.

2. Suche die Anwendung, für die du ein OpenAPI-Dokument veröffentlichen möchtest, und klicke das Chevron-Symbol auf ihrer Kachel. Die Seite REST API für diese API wird geöffnet.

   Wenn deine Anwendung nicht aufgelistet ist, hast du sie noch nicht als REST-API-Endpunkt veröffentlicht.

3. Klicke im Panel Service auf Bearbeiten.

4. Aktiviere die Option Dokumentation veröffentlichen. Dies teilt App Builder mit, das OpenAPI-Dokument zu generieren und zu veröffentlichen.

5. Gib optional eine Zusammenfassung und eine Beschreibung an.

6. Klicke Speichern.

Standardmäßig fügt App Builder alle Ressourcen der API in das OpenAPI-Dokument ein, es sei denn, du wählst Ressourcen aus, die ausgeschlossen werden sollen.

Schließe eine Ressource aus der API-Dokumentation aus

Wenn du eine einzelne Ressource aus der OpenAPI-Dokumentation, die generiert wird, ausschließen möchtest, wird dies auch über die Seite REST API der API konfiguriert:

1. Gehe zu IDE > REST APIs.

2. Suche die Anwendung, für die du ein OpenAPI-Dokument veröffentlichen möchtest, und klicke das Chevron-Symbol auf ihrer Kachel. Die Seite REST API für diese API wird geöffnet.

   Wenn deine Anwendung nicht aufgelistet ist, hast du sie noch nicht als REST-API-Endpunkt veröffentlicht.

3. Suche im Panel Ressourcen die Ressource, die du aus der Dokumentation ausschließen möchtest, und klicke das Symbol für Details. Die Seite REST-Ressource für diese Ressource wird geöffnet.

4. Klicke im Panel Ressource auf Bearbeiten.

5. Aktiviere die Option Aus Dokumentation ausschließen. Dies bewirkt, dass diese Ressource aus dem generierten Dokument ausgelassen wird, auch wenn Dokumentation veröffentlichen für die REST-API als Ganzes aktiviert ist.

6. Klicke Speichern.

Details zum OpenAPI-Dokument

Dieser Abschnitt beschreibt die Details des OpenAPI-Dokuments, das App Builder für die REST-APIs deiner Anwendung veröffentlichen kann.

Dokument-URL

Nach der Veröffentlichung ist das OpenAPI-Dokument unter der gleichen Basis-URL wie die REST-API deiner App 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 (beispielsweise 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 in OpenAPI-Datentypen zugeordnet werden.

• Eingabeparameter werden zu OpenAPI-Pfad- oder Abfrageparametern.

• (Ab App Builder 4.68.) Jedes Wurzelknotenfeld einer Ressource wird zu einem optionalen Abfrageparameter, der dokumentiert, wie man Ergebnisse nach diesem Feld filtert unter Verwendung eines einfachen Gleichheitsvergleichs.

• Nur benutzerdefinierte Ereignisse, die für REST-Exposition ausgewählt wurden, sind enthalten 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:

Veröffentlichte APIs auf Ihrem App-Builder-Server auflisten

Ab App Builder 4.68 können Sie jede Anwendung auf Ihrem App-Builder-Server mit einem veröffentlichten OpenAPI-Dokument entdecken, indem Sie die folgende URL abrufen:

.../rest/v1/services.json

Ersetzen Sie die Basis-URL durch die URL Ihres App-Builder-Servers. Dieser Endpunkt erfordert keine Authentifizierung.

Die Antwort ist ein JSON-Array mit einem Eintrag pro Anwendung, die ein veröffentlichtes OpenAPI-Dokument hat. Eine Anwendung ohne veröffentlichtes Dokument ist nicht enthalten:

[
  {
    "name": "Northwinds",
    "endpoint": "northwinds",
    "url": "https://example.com/rest/v1/northwinds",
    "openApiUrl": "https://example.com/rest/v1/northwinds/openapi.json"
  }
]

Bekannte Probleme und Einschränkungen

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