Discovering REST API documentation on a Liberty server
You can discover your REST API documentation on a Liberty server by using the API Discovery feature to find what REST APIs are available. Use the Swagger user interface to invoke the available REST endpoints.
Procedure
- 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 that are needed for your deployed application, such as servlet-3.0, jsp-2.2, and so on. Also ensure that 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>
- Expose 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 API Discovery feature, each application needs 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 that contains both the file content 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. 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.
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:
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.<featureManager> <feature>apiDiscovery-1.0</feature> <feature>jaxrs-1.0</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 exposing 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" } } }
- Use the getDocument method of the SPI
com.ibm.wsspi.rest.api.discovery.APIProvider interface.
- 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 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 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 on the page enables a comma-separated list of context roots to filter the content. This filtering works like the root query parameter. You may test drive the APIs by providing the required input values and click Try it out.
- 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.
- Use the GET
https://host:https_port/ibm/api/docs endpoint.
Subtopics
- Subscribe to Liberty REST API updates
The Liberty REST API discovery feature now exposes a new REST API, /ibm/api/docs/subscription, which allows users to subscribe to any REST API update, such as new APIs being available or old APIs being removed. This is useful when a user wants to be notified immediately of any changes in the endpoints that are provided by a particular Liberty instance. - REST endpoints for pushing APIs into IBM API Connect
Use the REST endpoint, which is a central location for both on-premises and cloud Liberty users, to visualize, call, and push APIs into IBM® API Connect.


http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twlp_api_discovery
File name: twlp_api_discovery.html