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

  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-Verbund-Controller-Server 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 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>
  2. Stellen Sie die Swagger 2.0-Dokumentation an Liberty-REST-Endpunkten bereit.

    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 das Feature "API Discovery" den Wert META-INF/swagger.json nicht findet, sucht das Feature 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.0</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ö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.

      Wenn Kontextstammverzeichnis/swagger.json nicht verfügbar ist, extrahiert das Feature "API Discovery" jede verfügbare Datei des Typs Kontextstammverzeichnis/swagger.yaml in das aus /ibm/api/docs und /ibm/api/explorer zusammengefasste Dokument. Das Feature apiDiscovery-1.0 kann swagger.json bzw. swagger.yaml praktisch verarbeiten, d. h., wenn die Webanwendung eine Datei des Typs server.xml, die ein Attribut des Typs docURL konfiguriert, eine Datei des Typs swagger.json bzw. swagger.yaml im Ordner META-INF oder JAX-RS- und Swagger-Annotationen hat, gibt der Aufruf von Kontextstammverzeichnis/swagger.json bzw. Kontextstammverzeichnis/swagger.yaml die Dokumentation für diese andere Konfiguration im angeforderten JSON- oder YAML-Format zurück.

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

    • 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 zwei optionale Abfrageparameter mit mehrfacher Kardinalität mit den Namen root und serverID.

      Der Abfrageparameter root kann die gefundenen Kontextstammverzeichnisse filtern. Ein 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.

      Der Abfrageparameter serverID kann die auf einem Liberty-Server verfügbaren REST-APIs filtern. Das Format von serverID ist Hostname,Benutzerverzeichnis,Servername. In diesem Format wird der Name des Hosts direkt gefolgt von einem Komma (,), dem Installationsverzeichnis, einem weiteren Komma (,) und dem Namen des Servers angegeben. 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 Cross-Origin Request Sharing (CORS) in der Datei server.xml des Member-Servers konfigurieren.

      Das folgende Snippet ist beispielsweise in der Datei server.xml des Member-Servers, der die API /IBMJMXConnectorREST/mbeanCount bereitstellt, erforderlich.

      <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"
              />

      Weitere Informationen zum Einrichten von CORS finden Sie unter Cross-Origin Request 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).
    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.


Symbol das den Typ des Artikels anzeigt. Taskartikel



Symbol für Zeitmarke Letzte Aktualisierung: 16.06.2016
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-dist&topic=twlp_api_discovery
Dateiname: twlp_api_discovery.html