Generating REST API documentation with MicroProfile OpenAPI
mpOpenAPI-1.1feature 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.1feature in a browser that uses a human friendly user interface.
Before you begin
- 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.0feature after the
mpOpenAPI-1.1is 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
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.
Configure various parts of the MicroProfile OpenAPI specification via the MicroProfile
config mechanism as needed for your application.
mpOpenAPI-1.1feature 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.1feature 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.
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.
mpOpenAPI-1.1feature in the Liberty server configuration.
<server> <featureManager> <feature>mpOpenAPI-1.1</feature> </featureManager> </server>
- Deploy your application.
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.