[8.5.5.8 or later]
This topic applies to WebSphere Application Server Liberty V8.5.5.9 and earlier. For the latest Liberty topics, see the WebSphere Application Server Liberty documentation.

Discovering REST API documentation on a Liberty server

You can discover your REST API documentation. Use the API Discovery feature to find what REST APIs are available on a Liberty server and then use the Swagger user interface to invoke the found REST endpoints.

Procedure

  1. Add the apiDiscovery-1.0 feature to a feature manager in the server.xml file of the Liberty server whose available REST APIs you want to find.

    The apiDiscovery-1.0 feature enables the REST API discovery bundles in the product. The feature also exposes documentation from Liberty REST endpoints such as JMX, if the server configuration uses the restConnector-1.0 feature, and collectives, if the server configuration uses the collectiveController-1.0 feature.

    Ensure the server configuration has all features needed for your deployed application, such as servlet-3.0, jsp-2.2, and so on. Also ensure the ports and user registry settings are correct for the deployed application.

    The following server.xml file has the apiDiscovery-1.0 feature:

    <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. Expose the Swagger 2.0 documentation in Liberty REST endpoints.

    You can configure the location of your API documentation in either of two ways:

    • Use the getDocument method of the SPI com.ibm.wsspi.rest.api.discovery.APIProvider interface.

      The getDocument method enables OSGi bundles from extension features to contribute REST API documents to the overall "master" documentation. For this release, the only supported DocType are DocType.Swagger_20_JSON and DocType.Swagger_20_YAML. Implementers of this interface can return the serialized JSON or YAML document as a java.lang.String value, or they can pass in a file reference (prefixed with file:///) to the JSON or YAML file location.

    • Use a deployed web application.

      Each web module can contribute its own REST API document. Multiple WAR files inside an enterprise application (EAR) file can have different Swagger 2.0 documents.

      The easiest way to expose the documentation of web modules is to include a swagger.json or swagger.yaml file inside the corresponding META-INF folder. During application deployment, the API Discovery feature looks for a META-INF/swagger.json value for each of the web modules. If a META-INF/swagger.json value is not found then the API Discovery feature looks for a META‐INF/swagger.yaml value.

      Another way to expose the REST API documentation for a web module is in a server.xml configuration file. Put a webModuleDoc element for each web module in a parent apiDiscovery element; for example:

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

      The webModuleDoc element must have a contextRoot attribute to uniquely identify the web module whose documentation you want to expose.

      An optional attribute, enabled, toggles the API discovery for a web module. The default of this attribute is true.

      The docURL attribute specifies where to find the documentation for the web module. The docURL value can start with a forward slash (/) so that the URL is relative to the context root; for example, /30ExampleServletInEar/swagger.json. Or the docURL value can start with http or https for an absolute URL that identifies the complete location of the documentation.

      [8.5.5.9 or later]If the web application does not provide a swagger.json or swagger.yaml file and the application contains JAX-RS annotated resources, you can automatically generate the Swagger document. The server configuration must have the apiDiscovery-1.0 feature and the jaxrs-1.1 or jaxrs-2.0 feature; for example:
      <featureManager>
          <feature>apiDiscovery-1.0</feature>
          <feature>jaxrs-1.0</feature>
      </featureManager>
      The product scans all classes in the web application for JAX-RS and Swagger annotations, searching for classes with @Path, @Api, and @SwaggerDefinition annotations. The product also automatically generates a corresponding Swagger document during the web application deployment or startup.

      [8.5.5.9 or later]You can also use the apiDiscovery-1.0 feature to merge previously generated documentation with the documentation that it finds during annotation scanning. The product searches for a META-INF/stub/swagger.json or META-INF/stub/swagger.yaml file in the web module. If the feature finds either of these files, the feature generates a Swagger document that contains both the content of the file and any JAX-RS and Swagger annotations that are in the web module. You can use this feature to document non-JAX-RS servlets because the documentation is automatically merged with the JAX-RS portions.

      [8.5.5.9 or later]Another way to expose the REST API documentation for a web module is to add swagger.json or swagger.yaml to the context root of the web application; for example:
      http://host:http_port/context_root/swagger.json
      or
      http://host:http_port/context_root/swagger.yaml
      A call to context_root/swagger.json or context_root/swagger.yaml returns the documentation for the context root in the requested JSON or YAML format. During web module startup, the API Discovery feature pulls any available context_root/swagger.json into the aggregated document from /ibm/api/docs and /ibm/api/explorer. If context_root/swagger.json is not available, then the API Discovery feature pulls any available context_root/swagger.yaml into the aggregated document from /ibm/api/docs and /ibm/api/explorer. The apiDiscovery-1.0 feature can handle swagger.json or swagger.yaml virtually, which means that if the web application has a server.xml file that configures a docURL attribute, a swagger.json or swagger.yaml file in the META-INF folder, or JAX-RS and Swagger annotations, then the call to context_root/swagger.json or context_root/swagger.yaml returns the documentation for this other configuration in the requested JSON or YAML format.
  3. Discover your API documentation.

    After you configure the location of your API documentation, you can discover it in the following ways:

    • Use the GET https://host:https_port/ibm/api/docs endpoint.

      This endpoint provides a valid Swagger 2.0 document with all available Liberty REST APIs merged into a single document. This is useful for consumer applications that want to programmatically navigate the set of available APIs, such as an API Management solution. Including an optional Accept header with an application/yaml value provides the Swagger 2.0 document in YAML format. This endpoint has a multiple-cardinality, optional query parameter called root that can filter the found context roots. For example, a call to GET https://host:https_port/ibm/api/docs?root=/myApp retrieves a Swagger 2.0 document that only has the documentation for the myApp context root.

    • Use the GET https://host:https_port/ibm/api/explorer endpoint.

      This endpoint provides an attractive, rendered HTML page that displays the content from the /ibm/api/docs URL. This page follows the same pattern as the standard online sample (http://petstore.swagger.io/), so that users can invoke the REST API. This endpoint helps you explore the available REST APIs on a Liberty server, and perhaps invoke them from the page. A filter input box enables a comma-separated list of context roots to filter the content. This filtering works like the root query parameter. You can test drive the APIs by providing the required input values and click the "Try it out" button.

    [8.5.5.9 or later]After you enable the apiDiscovery-1.0 feature, the management bean (MBean) that has the ObjectName value WebSphere:feature=apiDiscovery,name=APIDiscovery is registered in the Liberty MBeanServer. This MBean provides the following attributes:
    • The DocumentationURL attribute is the full URL of the /ibm/api/docs endpoint, and it displays the raw JSON or YAML documentation.
    • The ExplorerURL attribute is the full URL of the /ibm/api/explorer endpoint, and it displays the rendered UI of the documentation.

    You can use this MBean to learn whether REST API Discovery is enabled and where a client can reach it.


Icon that indicates the type of topic Task topic



Timestamp icon Last updated: Tuesday, 12 December 2017
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-libcore-mp&topic=twlp_api_discovery
File name: twlp_api_discovery.html