Discovering REST API documentation on a Liberty server

We can discover your REST API documentation on a Liberty server using the API Discovery feature to find what REST APIs are available. Use the Swagger user interface to start the available REST endpoints.

Stabilized feature: The apiDiscovery-1.0 feature is stabilized. We can continue to use the feature. However, instead of apiDiscovery-1.0, consider using the openapi-3.0 feature. We can update a Swagger V2 document created with apiDiscovery-1.0 to OpenAPI V3. We also can use the mpOpenAPI-1.0 feature, which supports the MicroProfile OpenAPI specification.

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

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

    The apiDiscovery-1.0 feature that is enabled on a Liberty collective controller server finds the REST APIs available on the controller and on its member servers with the apiDiscovery-1.0 feature enabled.

    Ensure that the server configuration has all features needed for your deployed application, such as jaxrs-2.0. Modify ports so that the server can open its HTTP ports.

    To display the private REST API documentation, configure a keystore service object entry and user registry settings in the server.xml file.

    However, to display only the public REST API documentation, add a keystore object entry only to access the document through HTTPS. Access the public documentation through HTTP does not require a keystore object entry nor user registry settings.

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

    If the web application contains two or more instances of the javax.ws.rs.core.Application class to correctly work with the API Discovery feature, each application needs a unique javax.ws.rs.@ApplicationPath value or url-mapping defined in the web.xml file.

    Enable the apiDiscovery-1.0 feature to merge current 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 containing both the file content and any JAX-RS and Swagger annotations in the web module. We can use this feature to document non-JAX-RS servlets because the documentation is automatically merged with the JAX-RS portions. We can configure the location of the 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 main 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 display 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 display 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 we want to display.

      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. If the web application does not provide a swagger.json or swagger.yaml file and the application contains JAX-RS annotated resources, we 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.1</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.

      We 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, it generates a Swagger document containing both the content of the file and any JAX-RS and Swagger annotations in the web module. We can use this feature to document non-JAX-RS servlets because the documentation is automatically merged with the JAX-RS portions.

      This technique can also be used to bypass annotation limitations, such as the displayed security definitions. For example, the following swagger.json, inside META-INF/stub, enables the annotations to reference these definitions: 

        { 
    "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. Discover your API documentation.

    After configuring the location of the API documentation, we can discover it in the following ways:

    • Use a REST API Client and run...

        GET https://host:https_port/ibm/api/docs

      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 has only 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 start the REST API. This endpoint helps you explore the available REST APIs on a Liberty server, and perhaps start them from the page.

      A filter input box on the page enables a comma-separated list of context roots to filter the content.

    • For a collective controller, use the GET https://host:https_port/ibm/api/collective/docs endpoint.

      This endpoint on the collective controller provides a valid Swagger 2.0 document with REST APIs available from the collective controller and its members with the apiDiscovery-1.0 feature enabled 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 one multiple-cardinality, optional query parameter called root.

      Query parameter root can filter the found context roots. For example, a call to GET https://host:https_port/ibm/api/collective/docs?root=/myApp retrieves a Swagger 2.0 document that has only the documentation for the myApp context root.

    • For a collective controller, use the GET https://host:https_port/ibm/api/collective/explorer endpoint.

      This endpoint on the collective controller provides an attractive, rendered HTML page that displays the content from the /ibm/api/collective/docs URL. This endpoint helps you explore the available REST APIs on the entire collective, and perhaps start them from the page. A filter input box on the page enables a comma-separated list of context roots and server ID to filter the content. The format of the server ID is "hostName,userDir,serverName". Quotation marks (") must surround the server ID. To test the APIs with the Try it out button, we must set up Cross Origin Request Sharing (CORS) in the server.xml of the member server.​

      For information about setting up CORS, see Configure Cross Origin Resource Sharing on a Liberty server.

      Note that the CORS requirement applies only to the collective version of the Swagger UI (https://host:https_port/ibm/api/collective/explorer).

    • Use other endpoints to display public REST documentation.

      Unlike the endpoints that are mentioned previously, accessing these endpoints does not require a keystore service object entry nor user registry settings. However, we can set a keystore service object entry to access the endpoints through HTTPS. By default, four endpoints are available for a collective controller:

      • 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

      By default, two endpoints are available for a server:

      • GET http://host:http_port/api/docs
      • GET http://host:http_port/api/explorer

      We can change the URL of the public endpoints with the publicURL attribute in the server.xml. For example, setting the following configuration in the server.xml makes the public REST API documentation available with GET http://host:http_port/myAPI/docs and http://host:http_port/myAPI/explorer:

      By default, all REST API endpoints contributed by deployed web applications, except internal server endpoints such as JMX REST Connector REST APIs, display in the public REST API documentation. We can set a public="false" attribute for a web module to not display REST APIs displayed by the module. For example, adding the following configuration to a server.xml causes REST APIs by the web module to not display in the public REST API documentation: 

        <apiDiscovery publicURL="myAPI">
   <webModuleDoc contextRoot="/22ExampleServlet" public="false" />
</apiDiscovery>

    • Use a swaggerDefinition attribute in a server.xml file to overwrite some fields in the Swagger 2.0 documents provided by the /docs endpoints.

      We can use swaggerDefinition to specify a JSON or YAML Swagger snippet containing fields to overwrite. We can overwrite the info, schemes, consumes, produces, and externalDocs fields.

    • For a collective controller, use a collective services query to list all available public RESTful APIs (services) in the entire collective.

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

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


Example

We can find more information about REST API Discovery in the OpenAPI interfaces.

Watch: The IBM WebSphere Application Server Liberty API discovery video on IBM MediaCenter provides examples and links to demonstration videos. (V8.5.5.9)