[17.0.0.3 und höher]

REST-API-Dokumentation mit OpenAPI generieren

Sie können Ihre REST-API-Dokumentation mit dem Feature openapi-3.0 generieren, das die OpenAPI-Spezifikation unterstützt. Dokumentieren Sie Ihre REST-APIs, geben Sie öffentliche und private APIs an, aktivieren Sie das Annotationsscannen und implementieren SIe Ihre Webanwendungen in einem Liberty-Server. Anschließend können Sie die von openapi-3.0 generierte API-Dokumentation in einem Browser anzeigen, der eine benutzerfreundliche Benutzerschnittstelle verwendet.

Vorbereitende Schritte

Erfahren Sie hier mehr über die OpenAPI-Spezifikation Version 3. Sie verwenden YAML- oder JSON-Dateien für die Dokumentation der REST-konformen APIs in Ihrer Anwendung.

[18.0.0.1 und höher]Wichtig: Sie können die Java-Schnittstellen und Programmiermodelle verwenden, die in der

MicroProfile-OpenAPI-Spezifikation Version 1.0 verfügbar sind. Das Feature mpOpenAPI-1.0 implementiert die MicroProfile-OpenAPI-Spezifikation.

Weitere Informationen zum Feature mpOpenAPI-1.0 finden Sie unter REST-API-Dokumentation mit MicroProfile OpenAPI 1.0 generieren.

Informationen zu diesem Vorgang

Sie können diese Features, wie z. B. die neue Benutzerschnittstelle, Annotationen und Programmierschnittstellen, mithilfe der folgenden Beispielanwendungen untersuchen.

Vorgehensweise

  1. Erstellen Sie die OpenAPI-Dokumentation.

    Sie können OpenAPIs auf verschiedene Arten dokumentieren und erstellen:

    • Geben Sie OpenAPI-Annotationen in Java-Code an, um eine Anwendung zu erweitern und zu dokumentieren.
    • Verwenden Sie einen Texteditor, um die API mit OpenAPI-Tags zu dokumentieren und speichern Sie anschließend die fertige openapi.yaml-Datei, openapi.yml- oder openapi.json-Datei im Verzeichnis META-INF Ihrer Anwendung.
    • Verwenden Sie die Programmierschnittstelle io.swagger.oas.integration.OpenAPIConfigurationBuilder, um das OpenAPI-Modell innerhalb der Anwendung zu erstellen. Diese Schnittstelle und die anderen zugehörigen Programmierschnittstellen für OpenAPI V3 finden Sie in den JAR-Dateien im Verzeichnis /wlp/dev/api/third-party. Damit das Feature openapi-3.0 den OpenAPIConfigurationBuilder starten kann, muss das Anwendungsarchiv eine Datei META-INF/services/io.swagger.oas.integration.OpenAPIConfigurationBuilder enthalten. Diese Datei enthält den vollständig qualifizierten Namen der Datei OpenAPIConfigurationBuilder.

      Weitere Informationen zu den verfügbaren Programmierschnittstellen, Beschreibungen der zugehörigen Funktionalität und Verwendungsbeispiele finden Sie unter OpenAPI-V3-Programmierschnittstellen.

  2. Aktivieren Sie das Feature openapi-3.0 in der Liberty-Serverkonfiguration.
    1. Fügen Sie das Feature openapi-3.0 dem Feature-Manager hinzu.
      <server>
         <featureManager>
            <feature>openapi-3.0</feature>
         </featureManager> 
      </server>
    2. Optional: Geben Sie an, dass eine Anwendungs-OpenAPI nicht öffentlich 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 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.

      Es gibt zwei Möglichkeiten, private APIs für Webanwendungen anzugeben:

      • Verwenden Sie in der Serverkonfiguration webModuleDoc und setzen Sie das Attribut public auf false.
        1. Fügen Sie ein openapi-Element hinzu und setzen Sie das zugehörige boolesche Attribut enablePrivateURL auf true.
        2. Fügen Sie ein webModuleDoc-Unterelement für jede Webanwendung hinzu und setzen Sie das zugehörige boolesche Attribut public für öffentliche APIs auf true und für private APIs auf false.

        Das folgende Beispiel macht die OpenAPIs der Anwendung "airlines" sichtbar und inaktiviert die Darstellung der OpenAPIs der Anwendung "airlinesAdmin".

        <openapi enablePrivateURL="true">
          <webModuleDoc contextRoot="/airlines" public="true" />
          <webModuleDoc contextRoot="/airlinesAdmin" public="false" />
        </openapi>

        Standardmäßig ist das Attribut public von webModuleDoc auf true gesetzt. Diese Konfiguration ist nur erforderlich, um Anwendungen, die privat bleiben sollen, zu inaktivieren.

      • Verwenden Sie in der API-Beschreibung eine Schlüsselworterweiterung für den Anbieter, um anzugeben, dass eine API privat ist.
        1. Fügen Sie ein openapi-Element zur Serverkonfiguration hinzu und setzen Sie das zugehörige boolesche Attribut enablePrivateURL auf true.
        2. Speichern Sie das Schlüsselwort x-ibm-private: true und den Wert in der Datei META-INF/openapi.yaml mit dem API-Beschreibungsdokument oder in der Datei mit einem anderen unterstützten Format. Dieser Wert setzt die Standardsichtbarkeit der API außer Kraft. Dieser Wert kann von einem webModuleDoc-Eintrag überschrieben werden.
    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 die Attribute des Elements webModuleDoc in der Serverkonfiguration.

      Geben Sie das Webmodul an, das Sie über das Attribut contextRoot ausblenden oder anzeigen möchten. Ändern Sie anschließend den Wert des Attributs enabled in false, um das Webmodul im OpenAPI-Dokument auszublenden. Der Standardwert für das Attribut enabled ist true. Im folgenden Beispiel ist das Modul "airlines" so konfiguriert, dass es im OpenAPI-Dokument angezeigt wird, während das Modul "airlinesAdmin" ausgeblendet wird.

      <openapi>
        <webModuleDoc contextRoot="/airlines" enabled="true" />
        <webModuleDoc contextRoot="/airlinesAdmin" enabled="false" />
      </openapi>
      Anmerkung: Das Attribut enabled wird für REST-API-Dokumente, die von anderen Liberty-Features bereitgestellt werden, nicht unterstützt.
  3. Optional: Aktivieren Sie den JAX-RS-Annotationsscan.

    Fügen Sie das jaxrs-2.0-Feature dem Feature-Manager hinzu. Wenn sowohl das jaxrs-2.0- als auch das openapi-3.0-Feature in einem Server aktiviert sind, scannt der Annotationsscanner alle Webanwendungen, die im Server implementiert sind, es sei denn, diese Funktion ist in der Serverkonfiguration inaktiviert. Der Scanner durchläuft Klassen, die mit den OpenAPI-3.0-Annotationen für die Klassendefinition und mit der JAX-RS-Annotation @Path annotiert sind. Sie können auf generierte OpenAPI-Dokumente mit dem öffentlichem OpenAPI-Endpunkt (api/docs) und dem privaten Endpunkt (ibm/api/docs) zugreifen.

  4. Aktivieren Sie die Sichtbarkeit von APIs anderer Anbieter für bestimmte Anwendungen. Wenn Sie das Laden von OpenAPI-Annotationen, -Modellen und -Programmiermodellen während der Laufzeit aktivieren möchten, müssen Sie die Sichtbarkeit von APIs anderer Anbieter für die bestimmte Anwendung aktivieren.
    1. Definieren Sie das Attribut apiTypeVisibility des classloader-Elements für die Sichtbarkeit von APIs anderer Anbieter. Fügen Sie third-party dem Element classloader in Ihrer Datei server.xml hinzu.

      Wenn Sie dem Element classloader das Element third-party im Attribut apiTypeVisibility nicht hinzufügen, verwendet es die Standarddefinition spec und ibm-api.

      <application id="scholar" name="Scholar" type="ear" location="scholar.ear">
        <classloader apiTypeVisibility="spec, ibm-api, third-party" commonLibraryRef="Alexandria" />
      </application>
  5. Optional: Aktivieren Sie die Validierung von OpenAPI-Dokumenten.

    Die Validierungsfunktion ist standardmäßig nicht verfügbar. Wenn Sie die Validierung aktivieren, wird jedes OpenAPI-Dokument, das von der Anwendung bereitgestellt wird, anhand der in der OpenAPI-V3-Spezifikation deklarierten Integritätsbedingungen über das Feature openapi-3.0 validiert. Wenn openapi-3.0 ein OpenAPI-zurückmelden findet, das nicht gültig ist, meldet das Feature in den Protokolldateien für jede Nichteinhaltung von Integritätsbedingungen einen Fehler. Das ungültige Dokument wird aus dem aggregierten OpenAPI-Dokument ausgeschlossen, das vom Endpunkt api/docs zurückgegeben wird. Wenn Sie die Validierung aktivieren möchten, setzen Sie das Attribut in der Datei server.xml validation auf true.

    <openapi validation="true"/>
  6. Implementieren Sie Ihre Anwendungen.
  7. Zeigen Sie das generierte API-Dokument in einem Browser an.

    Sie finden Ihre generierten API-Dokumente am Endpunkt /api/docs unter Angabe einer der folgenden URLs, 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.
    [17.0.0.4 und höher]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 das Attribut publicURL in der Datei server.xml anpassen. Sie können beispielsweise die folgende Konfiguration in der Datei server.xml definieren, um die öffentliche REST-API-Dokumentation verfügbar zu machen, indem Sie GET http://Liberty-Host:HTTP-Port/myAPI/docs und http://Liberty-Host:HTTP-Port/myAPI/explorer angeben.
    <openapi publicURL="myAPI" />

    Das OpenAPI-Dokument wird über Anwendungen hinweg für diesen Liberty-Server generiert und aggregiert. Das Dokument hat standardmäßig das YAML-Format. Wenn Sie Ihre Dokumentation mit Microsoft Internet Explorer 11 anzeigen, wird ein YAML-Dokument zurückgegeben, das nicht ordnungsgemäß formatiert ist. Verwenden sie als Ausweichmaßnahme einen Browser wie Mozilla Firefox oder Google Chrome. Wenn die http-Anforderung einen Accept-Header mit einem application/json-Wert hat, hat das Dokument das JSON-Format.

    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. Eine Aufruf an GET http://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 OpenAPI-Benutzerschnittstelle gibt die aggregiert Definitionen aus /api/docs wieder, um eine benutzerfreundliche Benutzerschnittstelle für die URL http://Liberty-Host:HTTP-Port/api/explorer anzuzeigen. Wenn Sie SSL aktivieren, können Sie auf die geschützte Benutzerschnittstelle unter https://Liberty-Host:HTTPS-Port/api/explorer zugreifen.

Sie können die privaten Webmodule durchsuchen, indem Sie das Attribut enablePrivateURL im Element openAPI der Datei server.xml aktivieren.
<openapi enablePrivateURL="true"/>
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 die öffentlichen und privaten 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.


Symbol das den Typ des Artikels anzeigt. Taskartikel

Dateiname: twlp_api_openapi.html