Generating REST API documentation with MicroProfile OpenAPI

The mpOpenAPI-1.1 feature provides an implementation of the MicroProfile OpenAPI specification and a set of Java interfaces and programming models that allow Java developers to natively produce OpenAPI v3 documents from their JAX-RS application. Then, you can view the API documentation that is generated by using the mpOpenAPI-1.1 feature in a browser that uses a human friendly user interface.

For information about using the Liberty MicroProfile OpenAPI feature versions 1.0 and later, see the Open Liberty website

Before you begin

Learn about the OpenAPI V3 specification and either the MicroProfile OpenAPI 1.1 specification or the MicroProfile OpenAPI 1.0 specification. You can use a static OpenAPI file in either YAML format or JSON format, MicroProfile OpenAPI annotations, or OpenAPI programming models to document the RESTful APIs in your application.

Avoid trouble:

Extension and extensions annotations are supported only at operation and class levels. Use other documentation mechanisms to specify extensions for other elements.
The OpenAPI UI behaves unexpectedly if you entered incorrect authorization credentials the first time. If correct credentials are entered later, the problem persists and might repeatedly prompt for credentials. Refresh the page and enter the correct credentials.
Enabling the transportSecurity-1.0 feature after the mpOpenAPI-1.1 is enabled might result in exceptions when you access the /openapi or openapi/ui endpoints. To avoid the problem, enable both features together. To resolve the problem after it occurs, disable and then enable the mpOpenAPI feature.

If multiple applications are deployed, one application is selected to produce the OpenAPI documentation. An informational message is output to identify the application that was selected. If the selected application is running, all other applications are ignored by the application processor. After the selected application is stopped, the next application is processed.

Procedure

Optional: Configure various parts of the MicroProfile OpenAPI specification via the MicroProfile config mechanism as needed for your application.
The mpOpenAPI-1.1 feature reads the configured values when your application is started.
- Configure one or more of the core configurations that available from the MicroProfile OpenAPI specification for your application.
- To add value, the mpOpenAPI-1.1 feature validates the final OpenAPI document that is generated for the application against the constraints that are declared in the OpenAPI Specification version 3.0. The validation results, a combination of errors and warnings, are output to the console log.
  Validation is enabled by default for applications. You can disable validation by setting the following configuration.
```
mp.openapi.extensions.liberty.validation=false
```
Choose one or a combination of the following ways to provide input for the generation of the resulting OpenAPI document as described in the documentation mechanisms.
- Use the programming model to provide a bootstrap or complete OpenAPI model tree.
- Use a text editor to write a static OpenAPI document in either YAML or JSON format, then place the openapi.yaml, openapi.yml, or the openapi.json file in the META-INF directory of your application.
- Specify MicroProfile OpenAPI annotations in Java code to augment and document an application.
- Use filter to update the OpenAPI model after it is built by using the documentation mechanisms.

Enable the mpOpenAPI-1.1 feature in the Liberty server configuration.

<server>
   <featureManager>
      <feature>mpOpenAPI-1.1</feature>
   </featureManager>
</server>

Deploy your application.
Optional: Check the validation results and ensure that your application conforms to the OpenAPI Specification version 3.0.
- Check the console log for validation errors.
- The events are grouped into errors and warnings. The message also includes the corresponding location in the produced document to help you identify the related element.
  Sample message:
```
CWWKO1650E: Validation of the OpenAPI document produced the following error(s):

 - Message: Required "scopes" field is missing or is set to an invalid value, Location: #/components/securitySchemes/reviewoauth/flows/authorizationCode
```
View the generated API document in a browser.
You can find the generated API document at the /openapi endpoint by using one of the following URLs.
- For non-SSL public APIs, view your document at http://Liberty_host:http_port/openapi.
- For SSL public APIs, view your document at https://Liberty_host:https_port/openapi.

Results

The OpenAPI user interface renders the definition from /openapi to display a UI at http://Liberty_host:http_port/openapi/ui. If you enable SSL, you can access the protected UI at https://Liberty_host:https_port/openapi/ui.