REST-API-Dokumentation auf einem Liberty-Server suchen

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 starten.
[18.0.0.1 und höher]Tipp: Sie können das Feature openapi-3.0 verwenden, um Ihre REST-API-Dokumentation zu erkennen. Das Feature openapi-3.0 kann als Folgeversion des Features apiDiscovery-1.0 kategorisiert werden. Sie können ein Swagger-V2-Dokument, das mit dem Feature apiDiscovery-1.0 erstellt wurde, auf OpenAPI V3 aktualisieren. Informationen hierzu finden Sie unter REST-API-Dokumentation mit OpenAPI generieren.

Vorgehensweise

  1. 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.

    [17.0.0.1 und höher]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>
  2. 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.:
      <featureManager>
          <feature>apiDiscovery-1.0</feature>
          <feature>jaxrs-1.1</feature>
      </featureManager>
      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.

      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"
          }
        }
      }
  3. 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.

      [17.0.0.1 und höher]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.

      [16.0.0.x]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.

      [16.0.0.x]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).
    • [17.0.0.1 und höher]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>
    • [17.0.0.1 und höher]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.

    • [17.0.0.1 und höher]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.

Beispiel

Weitere Informationen zur Erkennung von REST-APIs finden Sie in den OpenAPI-Schnittstellen und auf der WASdevWebsite.

IBM MediaCenter-Flash-Video mit Audiopräsentation 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)


Symbol das den Typ des Artikels anzeigt. Taskartikel

Dateiname: twlp_api_discovery.html