REST-API-Dokumentation auf einem Liberty-Server suchen
![[18.0.0.1 und höher]](../ng_v18001plus.gif)
Vorgehensweise
- Fügen Sie das Feature apiDiscovery-1.0 einem Feature-Manager in der Datei server.xml des Liberty-Servers hinzu, dessen verfügbare REST-APIs Sie suchen möchten.
Mit dem Feature apiDiscovery-1.0 werden die REST-API-Erkennungsbundles im Produkt aktiviert. Außerdem stellt das Feature Dokumentation von Liberty-REST-Endpunkten wie JMX bereit, wenn die Serverkonfiguration das Feature restConnector-1.0 verwendet, und von Verbünden, wenn die Serverkonfiguration das Feature collectiveController-1.0 verwendet.
Ist das Feature apiDiscovery-1.0 für einen Liberty-Verbundcontroller aktiviert, sucht es die REST-APIs, die auf dem Controller und den zugehörigen Member-Servern, für die das Feature apiDiscovery-1.0 aktiviert ist, verfügbar sind.
Vergewissern Sie sich, dass die Serverkonfiguration alle für Ihre implementierte Anwendung erforderlichen Features hat, wie z. B. jaxrs-2.0. Ändern Sie die Ports so, dass der Server die zugehörigen HTTP-Ports öffnen kann.
Wenn Sie die private REST-API-Dokumentation anzeigen möchten, konfigurieren Sie einen Keystore-Serviceobjekteintrag und Benutzerregistry-Einstellungen in der Datei server.xml.
Wenn Sie jedoch nur die öffentliche REST-API-Dokumentation anzeigen möchten, fügen Sie nur dann einen Keystore-Objekteintrag hinzu, wenn Sie auf das Dokument über HTTPS zugreifen möchten. Für den Zugriff auf die öffentliche Dokumentation über HTTP ist weder einene Keystore-Objekteintrag noch Benutzerregistry-Einstellungen erforderlich.
Die folgende Datei vom Typ server.xml hat das Feature apiDiscovery-1.0:
<server> <featureManager> <feature>apiDiscovery-1.0</feature> </featureManager> <httpEndpoint id="defaultHttpEndpoint" host="*" httpPort="8010" httpsPort="8020"/> <keyStore id="defaultKeyStore" password="Liberty"/> <basicRegistry id="basic" realm="ibm/api"> <user name="bob" password="bobpwd" /> </basicRegistry> </server>
- Zeigen Sie die Swagger 2.0-Dokumentation an Liberty-REST-Endpunkten an.
Wenn die Webanwendung zwei oder mehr Instanzen der Klasse javax.ws.rs.core.Application enthält, muss für jede Anwendung ein eindeutiger javax.ws.rs.@ApplicationPath- oder url-mapping-Wert in der Datei web.xml definiert sein.
Aktivieren Sie das Feature apiDiscovery-1.0, um die aktuelle Dokumentation mit der Dokumentation zusammenzuführen, die während des Annotationsscans gefunden wird. Das Produkt sucht im Webmodul nach der Datei META-INF/stub/swagger.json bzw. der Datei META-INF/stub/swagger.yaml. Wenn das Feature keine dieser Dateien findet, generiert es ein Swagger-Dokument, das den Inhalt der Datei sowie JAX-RS- und Swagger-Annotationen im Webmodul enthält. Sie können dieses Feature für die Dokumentation von anderen Servlets als JAX-RS-Servlets verwenden, weil die Dokumentation automatisch mit den JAX-RS-Teilen zusammengeführt wird. Sie können die Position Ihrer API-Dokumentation folgendermaßen konfigurieren:
- Verwenden Sie die Methode getDocument der SPI
com.ibm.wsspi.rest.api.discovery.APIProvider.
Mit der Methode getDocument können OSGi-Bundles aus Erweiterungsfeatures REST-API-Dokumente zur allgemeinen Masterdokumentation beisteuern. Für dieses Release werden ausschließlich die Dokumenttypen DocType.Swagger_20_JSON und DocType.Swagger_20_YAML unterstützt. Implementierer dieser Schnittstelle können das serialisierte JSON- oder YAML-Dokument als Wert java.lang.String zurückgeben oder eine Dateireferenz (mit dem Präfix file:///) an die JSON- oder YAML-Dateiposition übergeben.
- Verwenden Sie eine implementierte Webanwendung.
Jedes Webmodul kann ein eigenes API-Dokument beisteuern. Mehrere WAR-Dateien in einer EAR-Datei (Unternehmensanwendungsdatei) können unterschiedliche Swagger 2.0-Dokumente haben.
Die einfachste Möglichkeit für die Anzeige der Dokumentation von Webmodulen ist, eine Datei vom Typ swagger.json bzw. swagger.yaml in den entsprechenden Ordner META-INF einzuschließen. Bei der Anwendungsimplementierung sucht das Feature "API Discovery" nach einem Wert META-INF/swagger.json für jedes der Webmodule. Wenn kein META-INF/swagger.json-Wert gefunden wird, sucht das API-Erkennungsfeature anschließend nach dem Wert META INF/swagger.yaml.
Die REST-API-Dokumentation für ein Webmodul kann auch in einer Konfigurationsdatei vom Typ server.xml bereitgestellt werden. Fügen Sie ein Element webModuleDoc für jedes Webmodul in ein übergeordnetes Element apiDiscovery ein, z. B.:
<apiDiscovery> <webModuleDoc contextRoot="/30ExampleServletInEar" enabled="true" docURL="/swagger.json" /> <webModuleDoc contextRoot="/22ExampleServlet" enabled="false" /> <webModuleDoc contextRoot="/custom" enabled="true" docURL="http://petstore.swagger.io/v2/swagger.json" /> </apiDiscovery>
Das Element webModuleDoc muss ein Attribut contextRoot haben, um das Webmodul, dessen Dokumentation Sie bereitstellen möchten, eindeutig zu identifizieren.
Ein optionales Attribut, enabled, aktiviert bzw. inaktiviert API Discovery für ein Webmodul. Der Standardwert dieses Attributs ist true.
Das Attribut docURL gibt an, wo sich die Dokumentation für das Webmodul befindet. Der Wert von docURL kann mit einem Schrägstrich (/) beginnen, sodass die URL relativ zum Kontextstammverzeichnis ist, z. B. /30ExampleServletInEar/swagger.json. Der Wert von docURL kann aber auch mit http oder https beginnen, um eine absolute URL anzugeben, die die vollständige Position der Dokumentation angibt.
Wenn die Webanwendung keine Datei vom Typ swagger.json bzw. swagger.yaml hat und die Anwendung Ressourcen mit JAX-RS-Annotationen enthält, können Sie das Swagger-Dokument automatisch erstellen. Die Serverkonfiguration muss das Feature apiDiscovery-1.0 und das Feature jaxrs-1.1 oder das Feature jaxrs-2.0 haben, z. B.:
Das Produkt scannt alle Klassen in der Webanwendung nach JAX-RS- und Swagger-Annotationen. Dabei wird nach Klassen mit den Annotationen @Path, @Api und @SwaggerDefinition gesucht. Das Produkt generiert außerdem automatisch ein entsprechendes Swagger-Dokument während der Webanwendungsentwicklung oder beim Webanwendungsstart.<featureManager> <feature>apiDiscovery-1.0</feature> <feature>jaxrs-1.1</feature> </featureManager>
Sie können das Feature apiDiscovery-1.0 auch verwenden, um zuvor generierte Dokumentationen mit der Dokumentation zusammenzuführen, die während des Annotationsscans gefunden wird. Das Produkt sucht im Webmodul nach der Datei META-INF/stub/swagger.json bzw. der Datei META-INF/stub/swagger.yaml. Wenn das Feature keine dieser Dateien findet, generiert es ein Swagger-Dokument, das den Inhalt der Datei und JAX-RS- und Swagger-Annotiationen im Webmodul enthält. Sie können dieses Feature für die Dokumentation von anderen Servlets als JAX-RS-Servlets verwenden, weil die Dokumentation automatisch mit den JAX-RS-Teilen zusammengeführt wird.
Dieses Verfahren kann auch verwendet werden, um Annotationseinschränkungen zu umgehen, wie z. B. die Anzeige von Sicherheitsdefinitionen. Die folgende swagger.json-Datei im Verzeichnis META-INF/stub ermöglicht es Annotationen, diese Definitionen zu referenzieren:
{ "swagger" : "2.0", "securityDefinitions" : { "petstore_auth" : { "type" : "oauth2", "authorizationUrl" : "http://petstore.swagger.io/api/oauth/dialog," "flow" : "implicit", "scopes" : { "write_pets" : "modify pets in your account", "read_pets" : "read your pets" } }, "api_key" : { "type" : "apiKey", "name" : "api_key", "in" : "header" } } }
- Verwenden Sie die Methode getDocument der SPI
com.ibm.wsspi.rest.api.discovery.APIProvider.
- Suchen Sie Ihre API-Dokumentation.
Nach der Konfiguration der Position Ihrer API-Dokumentation, können Sie sie folgendermaßen suchen:
- Verwenden Sie den Endpunkt GET
https://Host:HTTPS-Port/ibm/api/docs.
Dieser Endpunkt stellt ein gültiges Swagger 2.0-Dokument bereit, das alle verfügbaren Liberty-REST-APIs enthält. Dies ist für Konsumentenanwendungen hilfreich, die programmsteuert im Satz der verfügbaren APIs navigieren möchten, z. B. eine API-Managementlösung. Wenn Sie einen optionalen Header Accept mit dem Wert application/yaml einschließen, wird das Swagger 2.0-Dokument im YAML-Format bereitgestellt. Dieser Endpunkt hat einen optionalen Abfrageparameter mit mehrfacher Kardinalität mit dem Namen root, der die gefundenen Kontextstammverzeichnisse filtern kann. Der Aufruf von GET https://Host:HTTPS-Port/ibm/api/docs?root=/myApp ruft beispielsweise ein Swagger 2.0-Dokument ab, das nur die Dokumentation für das Kontextstammverzeichnis myApp enthält.
- Verwenden Sie den Endpunkt GET
https://Host:HTTPS-Port/ibm/api/explorer.
Dieser Endpunkt stellt eine ansprechend dargestellte HTML-Seite bereit, auf der der Inhalt der URL /ibm/api/docs angezeigt wird. Diese Seite folgt demselben Muster wie das Standardonlinebeispiel (http://petstore.swagger.io/), sodass Benutzer die REST-API starten können. Mit diesem Endpunkt können Sie die verfügbaren REST-APIs auf einem Liberty-Server suchen und diese ggf. über diese Seite aufrufen.
Im Filtereingabefeld auf der Seite kann eine durch Kommas getrennte Liste mit Kontextstammverzeichnissen zum Filtern des Inhalts eingegeben werden.
- Verwenden Sie für einen Verbundcontroller
den Endpunkt GET
https://Host:HTTPS-Port/ibm/api/collective/docs.
Dieser Endpunkt im Verbundcontroller stellt ein gültiges Swagger 2.0-Dokument bereit, das die REST-APIs enthält, die im Verbundcontroller und seinen Membern, in denen das Feature apiDiscovery-1.0 aktiviert ist, verfügbar ist. Dies ist für Konsumentenanwendungen hilfreich, die programmsteuert im Satz der verfügbaren APIs navigieren möchten, z. B. eine API-Managementlösung. Wenn Sie einen optionalen Header Accept mit dem Wert application/yaml einschließen, wird das Swagger 2.0-Dokument im YAML-Format bereitgestellt.
Dieser Endpunkt hat eine mehrfache Kardinalität, einen optionalen Abfrageparameter mit dem Namen root.
Der Abfrageparameter root kann die gefundenen Kontextstammverzeichnisse filtern. Der Aufruf von GET https://Host:HTTPS-Port/ibm/api/collective/docs?root=/myApp ruft beispielsweise ein Swagger 2.0-Dokument ab, das nur die Dokumentation für das Kontextstammverzeichnis myApp enthält.
Bei Versionen vor Version 17.0.0.1 hat dieser Endpunkt zwei optionale Abfrageparameter mit mehrfacher Kardinalität mit den Namen root und serverID. Der Abfrageparameter root stimmt mit dem vorherigen überein. Der Abfrageparameter serverID kann die auf einem Liberty-Server verfügbaren REST-APIs filtern. Das Format von serverID ist Hostname,Benutzerverzeichnis,Servername. Ein Aufruf von GET https://Host:HTTPS-Port/ibm/api/collective/docs?serverID=samplehost.com:8020,/users/admin/wlp/usr,server1 ruft beispielsweise ein Swagger 2.0-Dokument ab, das nur die Dokumentation für REST-APIs enthält, die auf dem mit serverID angegebenen Liberty-Server vorhanden sind.
- Verwenden Sie für einen Verbundcontroller
den Endpunkt GET
https://Host:HTTPS-Port/ibm/api/collective/explorer.
Dieser Endpunkt im Verbundcontroller stellt eine ansprechend dargestellte HTML-Seite bereit, auf der der Inhalt der URL /ibm/api/collective/docs angezeigt wird. Mit diesem Endpunkt können Sie die verfügbaren REST-APIs im gesamten Verbund suchen und diese ggf. über diese Seite aufrufen. Im Filtereingabefeld auf der Seite kann eine durch Kommas getrennte Liste mit Kontextstammverzeichnissen und Servers-IDs zum Filtern des Inhalts eingegeben werden. Die Server-ID hat das Format "Hostname,Benutzerverzeichnis,Servername". Die Server-ID muss in Anführungszeichen (") eingeschlossen werden. Wenn Sie die APIs mit der Schaltfläche Probieren Sie es aus testweise ausführen möchten, müssen Sie CORS (Cross Origin Request Sharing) in der Datei server.xml des Member-Servers konfigurieren.
Bei Versionen vor Version 17.0.0.1 benötigen Sie ein Snippet, wie z. B. das nachfolgende Beispiel, in der Datei server.xml des Member-Servers, der die API /IBMJMXConnectorREST/mbeanCount bereitstellt.
<cors domain="/IBMJMXConnectorREST/mbeanCount" allowedOrigins="https://Controller-Hostname:HTTPS-Port" allowedMethods="GET,POST,DELETE,PUT,PATCH,OPTIONS" allowedHeaders="Content-Type,api_key,Authorization" allowCredentials="true" />
Informationen zur Konfiguration von CORS finden Sie unter Cross-Origin Resource Sharing in einem Liberty-Server konfigurieren.
Anmerkung: Die CORS-Voraussetzung gilt nur für die Verbundversion der Swaggerbenutzerschnittstelle (https://host:https_port/ibm/api/collective/explorer). Verwenden Sie andere Endpunkte, um die öffentliche REST-Dokumentation anzuzeigen.
Im Gegensatz zu den zuvor genannten Endpunkten sind für den Zugriff auf diese Endpunkte weder ein Keystore-Serviceobjekteintrag noch Benutzerregistry-Einstellungen erforderlich. Sie können jedoch einen Keystore-Serviceobjekteintrag für den Zugriff auf die Endpunkte über HTTPS konfigurieren.
Standardmäßig sind vier Endpunkte für einen Verbundcontroller verfügbar.- GET http://Host:HTTP-port/api/docs
- GET http://Host:HTTP-Port/api/explorer
- GET http://Host:HTTP-Port/api/collective/docs
- GET http://Host:HTTP-Port/api/collective/explorer
Standardmäßig sind zwei Endpunkte für einen Server verfügbar:- GET http://Host:HTTP-port/api/docs
- GET http://Host:HTTP-Port/api/explorer
Sie können die URL der öffentlichen Endpunkte über das Attribut publicURL in der Datei server.xml ändern. 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://Host:HTTP-Port/myAPI/docs und http://Host:HTTP-Port/myAPI/explorer angeben:
<apiDiscovery publicURL="myAPI" />
Standardmäßig werden alle REST-API-Endpunkte, die die implementierten Webanwendungen beitragen, mit Ausnahme der internen Serverendpunkte, wie z. B. JMX-REST-Connector-REST-APIs, in der öffentlichen REST-API-Dokumentation angezeigt. Sie können ein Attribut public="false" definieren, damit ein Webmodul die vom Modul verfügbar gemachten REST-APIs nicht anzeigt. Wenn Sie beispielsweise die folgende Konfiguration einer Datei server.xml hinzufügen, werden die von einem Webmodul verfügbar gemachten REST-APIs nicht in der öffentlichen REST-API-Dokumentation angezeigt:
<apiDiscovery publicURL="myAPI"> <webModuleDoc contextRoot="/22ExampleServlet" public="false" /> </apiDiscovery>
Verwenden Sie ein swaggerDefinition-Attribut in einer Datei server.xml, um einige Felder in den Swagger 2.0-Dokumenten zu überschreiben, die von den /docs-Endpunkten bereitgestellt werden.
Sie können das Snippet swaggerDefinition verwenden, um ein JSON- oder YAML-Swagger-Snippet anzugeben, das zu überschreibende Felder enthält. Sie können die Felder info, schemes, consumes, produces und externalDocs überschreiben.
Verwenden Sie für einen Verbundcontroller eine Verbundservicesabfrage, um alle verfügbaren öffentlichen REST-konformen APIs (Services) im gesamten Verbund abzufragen.
Nach der Aktivierung des Features apiDiscovery-1.0 wird die Management-Bean (MBean) mit dem ObjectName-Wert WebSphere:feature=apiDiscovery,name=APIDiscovery im Liberty-MBean-Server (MBeanServer) registriert. Diese MBean stellt die folgenden Attribute bereit:
- Das Attribut DocumentationURL ist die vollständige URL des Endpunkts /ibm/api/docs und zeigt die unformatierte JSON- oder YAML-Dokumentation an.
- Das Attribut ExplorerURL ist die vollständige URL des Endpunkts /ibm/api/explorer und zeigt die wiedergegebene Benutzerschnittstelle der Dokumentation an.
Sie können diese MBean verwenden, um zu ermitteln, ob die REST-API-Erkennung aktiviert ist und von wo ein Client sie erreichen kann.
- Verwenden Sie den Endpunkt GET
https://Host:HTTPS-Port/ibm/api/docs.
Beispiel
Weitere Informationen zur Erkennung von REST-APIs finden Sie in den OpenAPI-Schnittstellen und auf der WASdevWebsite.
Hinweis: Das Video IBM
WebSphere Application Server Liberty API discovery im IBM MediaCenter enthält Beispiele und Links zu Demovideos.
(Version 8.5.5.9)
Untergeordnete Themen
Swagger 2.0-Dokumentfelder überschreiben
Verwenden Sie ein swaggerDefinition-Attribut in einer Datei server.xml, um einige Felder in den Swagger 2.0-Dokumenten zu überschreiben, die von den /docs- und /explorer-Endpunkten bereitgestellt werden.Alle öffentlichen REST-konformen APIs in einem Verbund auflisten
Fragen Sie Services im Verbund ab, um API-Dokumentationen zu allen REST-konformen APIs (Services) im gesamten Verbund zu erkennen. Die Abfrage stellt die Dokumentation im Listenformat bereit.- Liberty-REST-API-Aktualisierungen subskribieren
Das Liberty-Feature für die REST-API-Erkennung stellt eine neue REST-API (/ibm/api/docs/subscription) bereit, mit der Benutzer REST-API-Aktualisierungen subskribieren können, wie z. B., wenn neue APIs verfügbar sind oder alte APIs entfernt werden. Dies ist hilfreich, wenn ein Benutzer umgehend über Änderungen an den Endpunkten, die von einer bestimmten Liberty-Instanz bereitgestellt werden, benachrichtigt werden will. - Liberty-REST-API-Aktualisierungen in einem Verbund subskribieren
Verwenden Sie die Subskriptions-API im Verbundcontroller, um umgehend über neue REST-APIs, entfernte APIs oder Änderungen an APIs, wie z. B. Änderungen der Endpunkte eines bestimmten Verbund-Member-Servers, benachrichtigt zu werden. - REST-Endpunkte für die Übertragung von APIs mit Push in IBM API Connect
Mit den REST-Endpunkt, der eine zentrale Position für lokale und Cloud-Liberty-Benutzer ist, können Sie APIs visualisieren, aufrufen und mit Push in IBM® API Connect übertragen.

Dateiname: twlp_api_discovery.html