REST-API-Dokumentation auf einem Liberty-Server erkennen
Sie erkennen die Dokumentation zu Ihren REST-APIs auf einem Liberty-Server, indem Sie mit dem Feature für die Erkennung von APIs nach den verfügbaren REST-APIs suchen. Über die Swagger-Benutzerschnittstelle können Sie die verfügbaren REST-Endpunkte aufrufen.
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.
Vergewissern Sie sich, dass die Serverkonfiguration alle für die implementierte Anwendung erforderlichen Features hat, wie z. B. servlet-3.0, jsp-2.2 usw. Stellen Sie außerdem sicher, dass die Port- und Benutzerregistry-Einstellungen für die implementierte Anwendung richtig sind.
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>
- Stellen Sie die Swagger 2.0-Dokumentation an Liberty-REST-Endpunkten bereit.
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-Wert oder -URL-Zuordnung 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 Bereistellung 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 ein Wert nicht gefunden wird, sucht META-INF/swagger.json und anschließend das API-Erkennungsfeature nach dem Wert META INF/swagger.yam.
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.0</feature> </featureManager>
Sie könne 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 Bereitstellung 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 programmgesteuert 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 aufrufen 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. Dieser Filter funktioniert wie der Abfrageparameter root. Sie können die APIs testweise ausführen, indem Sie die erforderlichen Eingabewerte angeben und auf die Schaltfläche Probieren Sie es aus klicken.
- 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.
Untergeordnete Themen
- 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. - 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.


http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twlp_api_discovery
Dateiname: twlp_api_discovery.html