REST-API-Dokumentation aggregieren

Sie können Ihre generierte REST-API-Dokumentation aggregieren, indem Sie das Feature openapi-3.1 verwenden, das die MicroProfile-OpenAPI-Spezifikation unterstützt. Dokumentieren Sie Ihre REST-APIs, geben Sie öffentliche und private APIs an und implementieren Sie Ihre Webanwendungen auf einem Liberty -Server. Anschließend können Sie die von openapi-3.1 generierte API-Dokumentation in einem Browser anzeigen, der eine benutzerfreundliche Benutzerschnittstelle verwendet.

Stabilisiertes Feature: Das Feature openapi-3.1 wurde stabilisiert. Sie können das Feature weiterhin verwenden. Die strategische Alternative ist jedoch die Verwendung eines MicroProfile-OpenAPI-Features wiempOpenAPI-3.0.

Vorbereitungen

Das openapi-3.1-Feature ist eine Erweiterung des Features mpOpenAPI-1.0, das die MicroProfile-OpenAPI-Spezifikation implementiert. Weitere Informationen zum Feature mpOpenAPI-1.0 finden Sie unter REST-API-Dokumentation mit MicroProfile OpenAPI 1.0.

Vorgehensweise

Erstellen Sie die OpenAPI-Dokumentation. Die Prozedur zum Erstellen der Dokumentation finden Sie unter REST-API-Dokumentation mit MicroProfile OpenAPI .
Aktivieren Sie das Feature openapi-3.1 in der Liberty-Serverkonfiguration.
1. Fügen Sie das Feature openapi-3.1 zum Feature-Manager hinzu:
```
<server>
   <featureManager>
      <feature>openapi-3.1</feature>
   </featureManager>
</server>
```
2. Optional: Geben Sie an, dass eine Anwendung OpenAPI privat ist. Standardmäßig ist die OpenAPI-Dokumentation öffentlich. Alle Benutzer können auf öffentliche APIs zugreifen, oft ohne Authentifizierung. Öffentliche APIs sind in der Ressource /api/docs resource dokumentiert. Sie können angeben, dass APIs privat bleiben. APIs für Verwaltungszwecke bleiben in der Regel privat. Private APIs, die mit Kennwörtern geschützt werden, sind in der Resssource /ibm/api/docs dokumentiert. Diese Ressource dokumentiert alle privaten APIs und alle öffentlichen APIs. Sie können eine private API für eine Webanwendung angeben, indem Sie die MicroProfile-Konfigurationseigenschaft mp.openapi.extensions.liberty.public=false auf Anwendungsebene definieren. Standardmäßig ist der Eigenschaftswert auf "tTrue" gesetzt. Diese Konfiguration ist nur erforderlich, um Anwendungen, die privat bleiben sollen, zu inaktivieren.
3. Optional: Geben Sie an, dass eine Anwendung nicht im OpenAPI -Dokument angezeigt wird. Standardmäßig werden ihre Webmodule, die die REST-API-Dokumente enthalten, im zusammengeführten OpenAPI-Dokument in der Ressource /api/docs als verfügbar angezeigt. Wenn Sie verhindern möchten, dass Webmodule im OpenAPI-Dokument angezeigt werden, ändern Sie den Wert für die MicroProfile-Konfigurationseigenschaft: mp.openapi.extensions.liberty.exclude.context.roots. Der Wert dieser Eigenschaft ist eine durch Kommas getrennte Liste mit Kontextstammverzeichnissen, die Sie ausblenden möchten. Geben Sie jedes auszublendende Webmodul anhand des zugehörigen Kontextstammverzeichnisses an und fügen Sie diese Kontextstammverzeichnisse dem Eigenschaftswert hinzu. Wenn Sie beispielsweise ein WEbmodul mit dem Kontextstammverzeichnis /airlinesAdmin ausblenden möchten, legen Sie Folgendes fest: mp.openapi.extensions.liberty.exclude.context.roots=/airlinesAdmin. Diese Eigenschaft wird gelesen, wenn das Feature openapi-3.1 aktiviert ist.
Implementieren Sie Ihre Anwendung.
Sie können Ihr generiertes API-Dokument am /api/docs -Endpunkt finden, indem Sie eine der folgenden URLs verwenden, je nachdem, ob Ihre API öffentlich oder privat ist.
- - Wenn Sie Ihr Dokument mit den öffentlichen APIs ohne SSL anzeigen möchten, verwenden Sie die folgende URL: http://Liberty_host:http_port/api/docs.
  - Wenn Sie Ihr Dokument mit den öffentlichen APIs mit SSL anzeigen möchten, verwenden Sie die folgende URL: https://Liberty_host:https_port/api/docs.
  - Wenn Sie Ihr Dokument mit den privaten APIs mit SSL anzeigen möchten, verwenden Sie die folgende URL: https://Liberty_host:https_port/ibm/api/docs.
Tipp:
Standardmäßig sind zwei Endpunkte für einen Server verfügbar.
- GET http://Liberty_host:http_port/api/docs
  
  GET http://Liberty_host:http_port/api/explorer
Sie können URLs für öffentliche Endpunkte über die MicroProfile-Konfigurationseigenschaft anpassen: mp.openapi.extensions.liberty.public.url. Diese Eigenschaft wird gelesen, wenn das Feature openapi-3.1 aktiviert ist. Das folgende Beispiel zeigt, wie die MicroProfile-Konfiguration aussehen muss, damit Sie die öffentliche REST-API-Dokumentation mit GET verfügbar machen können: GET http://Liberty_host:http_port/myAPI/docs und http://Liberty_host:http_port/myAPI/explorer.
```
mp.openapi.extensions.liberty.public.url=myAPI
```
Das Dokument OpenAPI wird anwendungsübergreifend für diesen Liberty -Server generiert und aggregiert. Das Dokument hat standardmäßig das YAML-Format. Wenn die HTTP-Anforderung einen Accept-Header mit einem application/json-Wert hat, hat das Dokument das JSON-Format. Alternativ ist es möglich, den Abfrageparameter format zu verwenden: http://Liberty_host:http_port/api/docs?format=json
Tipp:
Sie können das OpenAPI-Dokument nach Kontextstammverzeichnis filtern. Sowohl der öffentliche Endpunkt (api/docs) als auch der private Endpunkt (ibm/api/docs) unterstützen einen Abfrageparameter root, der die gefundenen Kontextstammverzeichnisse filtern kann. Beispiel:
GEThttp://Liberty_host:http_port/api/docs?root=/myApp ruft ein OpenAPI V3 -Dokument ab, das nur die Dokumentation für das Kontextstammverzeichnis myApp enthält.

Ergebnisse

Die Benutzerschnittstelle OpenAPI gibt die aggregierten Definitionen aus /api/docs in http://Liberty_host:http_port/api/explorerwieder. Wenn Sie „ SSL “ aktivieren, können Sie auf die geschützte Benutzeroberfläche unter zugreifen https://Liberty_host:https_port/api/explorer.

Sie können die privaten Webmodule durchsuchen, indem Sie die MicroProfile-Konfigurationseigenschaft wie folgt setzen: mp.openapi.extensions.liberty.enable.private.url=true. Diese Eigenschaft wird gelesen, wenn das Feature openapi-3.1 aktiviert ist.

Wenn das Browsing für private Webmodule aktiviert ist, verwenden Sie https://Liberty_host:https_port/ibm/api/explorer , um die benutzerfreundliche Benutzerschnittstelle für öffentliche und private Webmodule anzuzeigen.

Sie können alle REST-konformen Endpunkt Ihrer Anwendung in dieser Benutzerschnittstelle anzeigen. Sie können auch angezeigte Endpunkte filtern, um sich auf bestimmte Anwendungen zu konzentrieren.