MicroProfile OpenAPI
4.0
3.1
3.0
2.0
1.1
1.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 4.0 feature, add the following element declaration into your server.xml file, inside the featureManager element:

<feature>mpOpenAPI-4.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

In MicroProfile OpenAPI 4.0 and later, all deployed applications and modules are included in the OpenAPI documentation by default. However, you can configure which applications and modules are included.

For example, the following configuration is for the sample_app application, which consists of an EAR file containing five web modules.

<mpOpenAPI>
  <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 excludeModule elements exclude the module-3 and module-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 in server.xml using application, webApplication, or enterpriseApplication. For example:

    <webApplication name="application1" location="application1-v1.war" />

    If the application is deployed in the dropins directory or if the name attribute is not specified, the name defaults to the archive filename without the file extension.

  • The module name is specified in the web module’s web.xml file. If no web.xml file exists or if it does not specify a name, the module name defaults to the file name without the file extension.

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.

Selecting the OpenAPI specification version

If you are using a feature that supports more than one version of the OpenAPI specification, you can switch between versions with configuration. You might need to do this if you or your users use tools or libraries that don’t yet support a newer version of the OpenAPI specification.

For example, mpOpenAPI-4.0 defaults to OpenAPI 3.1, but you can specify the following configuration to set it to OpenAPI 3.0.

<mpOpenAPI openAPIVersion="3.0"/>

Feature configuration elements

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

Features that this feature enables

Supported Java versions

  • JavaSE-11.0

  • JavaSE-17.0

  • JavaSE-21.0

  • JavaSE-23.0

Features that enable this feature

Developing a feature that depends on this feature

If you are developing a feature that depends on this feature, include the following item in the Subsystem-Content header in your feature manifest file.

io.openliberty.mpOpenAPI-4.0; type="osgi.subsystem.feature"