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, legen Sie öffentliche und private APIs fest, aktivieren Sie das Scannen von Anmerkungen und stellen Sie Ihre Webanwendungen auf einem Liberty -Server bereit. Anschließend können Sie die von openapi-3.0 generierte API-Dokumentation in einem Browser anzeigen, der eine benutzerfreundliche Benutzerschnittstelle verwendet.

Stabilisierte Funktionen: Die Funktionen „ OpenAPI “ openapi-3.0 und openapi-3.1„ V3 “ sowie „“ und „“ wurden stabilisiert. Sie können die Features weiterhin verwenden. Die strategische Alternative besteht jedoch darin, eine Funktion wie mpOpenAPI-3.0„ MicroProfileOpenAPI “ zu verwenden.

Weitere Informationen zur Verwendung von MicroProfile OpenAPI mit Liberty finden Sie auf der Website Open Liberty

Vorbereitungen

Erfahren Sie mehr über die Spezifikation „ OpenAPIV3 ”. Sie verwenden YAML- oder JSON-Dateien für die Dokumentation der REST-konformen APIs in Ihrer Anwendung.

Sie können die Java-Schnittstellen und Programmiermodelle verwenden, die in der Spezifikation „ MicroProfileOpenAPI ” (Version 1.0 ) verfügbar sind. Das Feature mpOpenAPI-1.0 implementiert die MicroProfile-OpenAPI-Spezifikation. Weitere Informationen zu den Funktionen von mpOpenAPI-1.0 und späteren Versionen finden Sie unter Generieren von REST-API-Dokumentation mit MicroProfile OpenAPI.

Informationen zu dieser Task

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

Versuchen Sie, eine RESTful-Anwendung mithilfe von Annotationen aus „ OpenAPI “ in Java™-Code zu dokumentieren, indem Sie die Beispielanwendung „ OpenAPI “ V3 verwenden.
Sehen Sie sich ein Beispiel für ein Dokument im YAML-Format „ OpenAPI “ ( V3 ) an, das mit einem Texteditor erstellt wurde: OpenAPI V3 example document.
Erweitern Sie die openapi-3.0 Funktion mithilfe der io.swagger.oas.integration.OpenAPIConfigurationBuilder Programmierschnittstellen mit dem Beispiel für die Programmierschnittstelle „ OpenAPIConfiguration “.

Vorgehensweise

Erstellen Sie die OpenAPI-Dokumentation.
Sie können OpenAPIs auf verschiedene Arten dokumentieren und erstellen:
- Geben Sie Annotationen von „ OpenAPI “ im 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 ihrer Funktionen und Anwendungsbeispiele finden Sie unter „ OpenAPI - V3 -Programming Interfaces “.
Aktivieren Sie die openapi-3.0 Funktion in der Liberty -Serverkonfiguration.
1. Fügen Sie die openapi-3.0 Funktion zum Funktionsmanager hinzu.
```
<server>
   <featureManager>
      <feature>openapi-3.0</feature>
   </featureManager>
</server>
```
2. Optional: Geben Sie an, dass ein Anwendungs 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 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: Legen Sie fest, dass eine Anwendung nicht im Dokument „ OpenAPI “ 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>
```
  Hinweis: Das enabled Attribut wird für REST-API-Dokumente, die von anderen Liberty -Funktionen bereitgestellt werden, nicht unterstützt.
Optional: Aktivieren Sie das Scannen von JAX-RS-Annotationen.

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.
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 apiTypeVisibility Attribut des classloader Elements als Sichtbarkeit der Drittanbieter-API. Fügen Sie third-party zum Element classloader in Ihrer server.xml Datei hinzu.
  
  Wenn Sie dem Element classloader das Element third-party im Attribut apiTypeVisibility nicht hinzufügen, verwendet es die Standarddefinition spec, stable und ibm-api.
```
<application id="scholar" name="Scholar" type="ear" location="scholar.ear">
  <classloader apiTypeVisibility="spec, ibm-api, stable, third-party" commonLibraryRef="Alexandria" />
</application>
```
Optional: Aktivieren Sie die Validierung von Dokumenten im Format „ OpenAPI “.

Die Validierungsfunktion ist standardmäßig inaktiviert. 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. Um die Validierung zu aktivieren, setzen Sie das validation Attribut in der server.xml Datei true auf.
```
<openapi validation="true"/>
```
Implementieren Sie Ihre Anwendungen.
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.
- Für nicht SSL öffentliche APIs finden Sie Ihr Dokument unter http://Liberty_host:http_port/api/docs.
- Für öffentliche APIs von SSL finden Sie Ihr Dokument unter https://Liberty_host:https_port/api/docs.
- Für private APIs von SSL finden Sie Ihr Dokument unter https://Liberty_host:https_port/ibm/api/docs.
Tipp: Standardmäßig sind für einen Server zwei Endpunkte 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. Das folgende Beispiel veranschaulicht die Konfiguration in der server.xml Datei, um die öffentliche REST-API-Dokumentation mit verfügbar GET http://Liberty_host:http_port/myAPI/docs and http://Liberty_host:http_port/myAPI/explorerzu machen.
```
<openapi publicURL="myAPI" />
```
Das Dokument „ OpenAPI “ wird für diesen Liberty -Server generiert und über alle Anwendungen hinweg 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. Als Workaround verwenden Sie 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 Dokument „ OpenAPI “ nach Kontextstamm 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. Beispielsweise ruft ein Aufruf von ein Dokument „ GET http://Liberty_host:http_port/api/docs?root=/myAppOpenAPIV3 “ ab, das nur die Dokumentation für den myApp Kontextstamm enthält.

Ergebnisse

Die Benutzeroberfläche „ OpenAPI “ rendert die aggregierten Definitionen von, /api/docs um eine benutzerfreundliche Oberfläche unter http://Liberty_host:http_port/api/exploreranzuzeigen. 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 das Attribut enablePrivateURL im Element openAPI der Datei server.xml aktivieren.

<openapi enablePrivateURL="true"/>

Wenn das private Webmodul-Browsing aktiviert ist, verwenden Sie https://Liberty_host:https_port/ibm/api/explorer , um die benutzerfreundliche Benutzeroberfläche sowohl für öffentliche als auch für 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.