Discovering REST API documentation on a Liberty server

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.

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

<featureManager>
    <feature>apiDiscovery-1.0</feature>
    <feature>jaxrs-1.1</feature>
</featureManager>

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

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

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

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.

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.

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, you must set up Cross Origin Request Sharing (CORS) in the server.xml of the member server.​

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

Unlike the endpoints that are mentioned previously, accessing these endpoints does not require a keystore service object entry nor user registry settings. However, you can set a keystore service object entry to access the endpoints through HTTPS.

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

<apiDiscovery publicURL="myAPI" />

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

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