Aggregating REST API documentation

You can aggregate your generated REST API documentation by using the openapi-3.1 feature, which supports the MicroProfile OpenAPI specification. Document your REST APIs, specify public and private APIs, and deploy your web applications to a Liberty server. Then, you can view the API documentation that is generated by openapi-3.1 in a browser that uses a human-friendly user interface.

Stabilized feature: The openapi-3.1 feature is stabilized. You can continue to use the feature. However, the strategic alternative is to use a MicroProfile OpenAPI feature such as mpOpenAPI-3.0.

Before you begin

The openapi-3.1 feature is an extension of the mpOpenAPI-1.0 feature that implements the MicroProfile OpenAPI specification. For more information about the mpOpenAPI-1.0 feature, see Generating REST API documentation with MicroProfile OpenAPI 1.0.

Procedure

Build the OpenAPI documentation. Review Generating REST API documentation with MicroProfile OpenAPI for the procedure on building the documentation.
Enable the openapi-3.1 feature in the Liberty server configuration.
1. Add the openapi-3.1 feature to the feature manager:
```
<server>
   <featureManager>
      <feature>openapi-3.1</feature>
   </featureManager>
</server>
```
2. Optional: Specify that an application OpenAPI is private. By default, OpenAPI documentation is public. All users can access public APIs, often without authentication. Public APIs are documented in the /api/docs resource. You can specify that APIs remain private. APIs for administrative use are typically kept private. Private APIs, which use passwords for protection, are documented in the /ibm/api/docs resource. This resource documents all private APIs and all public APIs. You can specify a private API for a web application by setting the MicroProfile configuration property, mp.openapi.extensions.liberty.public=false, at the application level. By default, the property's value is true. This configuration is needed only to disable applications that you want to keep private.
3. Optional: Specify that an application not appear in the OpenAPI document. By default, your web modules that contain REST API documents appear in the merged OpenAPI document available in the /api/docs resource. To keep web modules from appearing in the OpenAPI document, set the value of the MicroProfile configuration property: mp.openapi.extensions.liberty.exclude.context.roots. The value of this property is a comma-separated list of context roots that you want to hide. Identify each web module that you want to hide by their context roots and add those context roots to the value of the property. For example, to hide a web module with the context root /airlinesAdmin you would set mp.openapi.extensions.liberty.exclude.context.roots=/airlinesAdmin. This property is read when the openapi-3.1 feature is enabled.
Deploy your application.
You can find your generated API document at the /api/docs endpoint by using one of the following URLs, depending on whether your API is public or private.
- - For non-SSL public APIs, view your document at http://Liberty_host:http_port/api/docs.
  - For SSL public APIs, view your document at https://Liberty_host:https_port/api/docs.
  - For SSL private APIs, view your document at https://Liberty_host:https_port/ibm/api/docs.
Tip:
By default, two endpoints are available for a server.
- GET http://Liberty_host:http_port/api/docs
  
  GET http://Liberty_host:http_port/api/explorer
You can customize URLs for public endpoints with the MicroProfile configuration property: mp.openapi.extensions.liberty.public.url. This property is read when the openapi-3.1 feature is enabled. The following example illustrates the MicroProfile configuration to make the public REST API documentation available with GET http://Liberty_host:http_port/myAPI/docs and http://Liberty_host:http_port/myAPI/explorer.
```
mp.openapi.extensions.liberty.public.url=myAPI
```
The OpenAPI document is generated and aggregated across applications for that Liberty server. The document is in YAML format by default. If the HTTP request has an Accept header with an application/json value, the document is in JSON format. Alternatively, it is possible to use the format query parameter: http://Liberty_host:http_port/api/docs?format=json
Tip:
You can filter the OpenAPI document by context root. Both the public endpoint (api/docs) and the private endpoint (ibm/api/docs) support a query parameter, root, that can filter the found context roots. For example, a call to
GEThttp://Liberty_host:http_port/api/docs?root=/myApp retrieves an OpenAPI V3 document that has only the documentation for the myApp context root.

Results

The OpenAPI user interface renders the aggregated definitions from /api/docs at http://Liberty_host:http_port/api/explorer. If you enable SSL, you can access the protected UI at https://Liberty_host:https_port/api/explorer.

You can browse the private web modules by setting the MicroProfile configuration property: mp.openapi.extensions.liberty.enable.private.url=true. This property is read when the openapi-3.1 feature is enabled.

When the private web module browsing is enabled, use https://Liberty_host:https_port/ibm/api/explorer to display the human-friendly UI for both public and private web modules.

You can view all RESTful endpoints from your application in this user interface. You can also filter displayed endpoints to focus on specific applications.