MicroProfile OpenAPI4.03.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.0 feature, add the following element declaration into your server.xml
file, inside the featureManager
element:
<feature>mpOpenAPI-3.0</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.
Configure OpenAPI documentation for a multi-module application
Only the first module of the first deployed application is included in the OpenAPI documentation by default. However, you can configure the MicroProfile OpenAPI feature to merge the OpenAPI documentation for multiple applications or modules into a single document.
For example, the following configuration is for the sample_app
application, which consists of an EAR
file containing five web modules.
<mpOpenAPI>
<includeApplication>all</includeApplication>
<excludeModule>sample_app/module-3</excludeModule>
<excludeModule>sample_app/module-5</excludeModule>
<info title="A multi-module sample application"
description="This is a sample application."
version="2.0.1"
termsOfService="http://example.com/sample_app/terms"
contactName="API Support"
contactUrl="http://www.example.com/sample_app/support"
contactEmail="[email protected]"
licenseName="License 2.0"
licenseUrl="https://www.example.org/licenses/LICENSE-2.0.html"
/>
</mpOpenAPI>
The
includeApplication
element specifies that all applications are included in the final OpenAPI document.The
excludeModule
elements exclude themodule-3
andmodule-5
web modules.The
info
element sets the info section for the final OpenAPI document, which documents web modules 1, 2, and 4.
Naming applications and modules
The application name is determined by the value of the
name
attribute when the application is deployed inserver.xml
usingapplication
,webApplication
, orenterpriseApplication
. For example:<webApplication name="application1" location="application1-v1.war" />
If the application is deployed in the
dropins
directory or if thename
attribute is not specified, the name defaults to the archive filename with the extension removed.The module name is specified in the web module’s
web.xml
file. If there is noweb.xml
file or if it does not specify a name, the module name defaults to the filename with the extension removed.
For more information, see Multiple application and multi-module application support with MicroProfile OpenAPI.
Override the info section in the OpenAPI document
You can override the info
section of the OpenAPI document specifying the info
element within the mpOpenAPI
element:
<mpOpenAPI>
<info title="Example API"
version="1.0"
description="This is an example API"/>
</mpOpenAPI>
Overriding the info
section is useful for documenting multiple modules or applications. Without an override, the info
section is a standard version that indicates that documentation from several modules was merged.
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