MicroProfile OpenAPI3.13.02.01.11.0
This feature provides support for the Eclipse MicroProfile OpenAPI specification for enterprise Java.
You can use MicroProfile Config properties to provide configuration values for MicroProfile OpenAPI. For more information, see MicroProfile Config Properties: OpenAPI.
Enabling this feature
To enable the MicroProfile OpenAPI 3.1 feature, add the following element declaration into your server.xml
file, inside the featureManager
element:
<feature>mpOpenAPI-3.1</feature>
Examples
Configure MicroProfile OpenAPI documentation endpoints
MicroProfile OpenAPI generates and serves OpenAPI documentation for Jakarta RESTful Services or JAX-RS applications that are deployed to the Open Liberty runtime. The OpenAPI documentation is served from the <host>:<port>/openapi
endpoint and a user interface for browsing this documentation is served from the <host>:<port>/openapi/ui
endpoint.
You can configure the paths for these endpoints. Specify the docPath
and uiPath
attributes for the mpOpenAPI
element in your server.xml
file. For example, the following configuration sets the OpenAPI documentation for an appA
application to /appA/openapi
, while the UI to browse that documentation is available at /appA/openapi/docUi
:
<mpOpenAPI docPath="/appA/openapi" uiPath="/appA/openapi/docUi" />
When the uiPath
attribute is not set, it defaults to the value of the docPath
attribute with /ui
appended.
Examples
Configure OpenAPI documentation for a multi-module application
You can specify MicroProfile Config properties to configure the Microprofile OpenAPI feature to merge OpenAPI documentation for multiple applications or modules into a single document.
In the following microprofile-config.properties
file example, an OpenAPI document is configured for the sample_app
application, which consists of an EAR
file with five web modules.
mp.openapi.extensions.liberty.merged.include=all
mp.openapi.extensions.liberty.merged.exclude=sample_app/module-3,sample_app/module-5
mp.openapi.extensions.liberty.merged.info=
{
"title": "A multi-module sample application",
"description": "This is a sample application.",
"termsOfService": "http://example.com/sample_app/terms",
"contact": {
"name": "API Support",
"url": "http://www.example.com/sample_app/support",
"email": "[email protected]"
},
"license": {
"name": "License 2.0",
"url": "https://www.example.org/licenses/LICENSE-2.0.html"
},
"version": "2.0.1"
}
The
mp.openapi.extensions.liberty.merged.include
property specifies that all five modules are included in the final OpenAPI document.The
mp.openapi.extensions.liberty.merged.exclude
overrides themp.openapi.extensions.liberty.merged.include
property to exclude themodule-3
andmodule-5
web modules.The
mp.openapi.extensions.liberty.merged.info
property sets theinfo
section for the final OpenAPI document, which documents web modules 1, 2, and 4.
For more information, see Multiple application and multi-module application support with MicroProfile OpenAPI
Stable API packages provided by this feature
org.eclipse.microprofile.openapi
org.eclipse.microprofile.openapi.annotations
org.eclipse.microprofile.openapi.annotations.callbacks
org.eclipse.microprofile.openapi.annotations.enums
org.eclipse.microprofile.openapi.annotations.extensions
org.eclipse.microprofile.openapi.annotations.headers
org.eclipse.microprofile.openapi.annotations.info
org.eclipse.microprofile.openapi.annotations.links
org.eclipse.microprofile.openapi.annotations.media
org.eclipse.microprofile.openapi.annotations.parameters
org.eclipse.microprofile.openapi.annotations.responses
org.eclipse.microprofile.openapi.annotations.security
org.eclipse.microprofile.openapi.annotations.servers
org.eclipse.microprofile.openapi.annotations.tags
org.eclipse.microprofile.openapi.models
org.eclipse.microprofile.openapi.models.callbacks
org.eclipse.microprofile.openapi.models.examples
org.eclipse.microprofile.openapi.models.headers
org.eclipse.microprofile.openapi.models.info
org.eclipse.microprofile.openapi.models.links
org.eclipse.microprofile.openapi.models.media
org.eclipse.microprofile.openapi.models.parameters
org.eclipse.microprofile.openapi.models.responses
org.eclipse.microprofile.openapi.models.security
org.eclipse.microprofile.openapi.models.servers
org.eclipse.microprofile.openapi.models.tags
org.eclipse.microprofile.openapi.spi