Documentation: MicroProfile OpenAPI 4.0

Feature epic details

For the title of this issue, type: Documentation, Development epic name
Link to development epic: OpenLiberty/open-liberty#27311
Target GA release: 24.0.0.12

Operating systems

Does the documentation apply to all operating systems?

[x] Yes
[ ] No; specify operating systems: __

Summary

Provide a concise summary of your feature. What is the update, why does it matter, and to whom? What do 80% of target users need to know to be most easily productive using your runtime update?

OpenAPI is a standard for documenting RESTful interfaces. An OpenAPI document can be used to create user-facing API docs, as a design spec for an API to be developed or for generating client code to access the API.

MicroProfile OpenAPI automatically generates OpenAPI documentation for applicationsusing Jakarta RESTful Web Services. Application developers can add more detail to the generated documentation by adding annotations or by using the lower-level Model API to modify the document directly. End users can retrieve the final document from the server via the /openapi endpoint.

Liberty also provides a web-based UI to browse the OpenAPI documentation and probe the API at the /openapi/ui endpoint.

Configuration

List any new or changed properties, parameters, elements, attributes, etc. Include default values and configuration examples where relevant:

Configure the OpenAPI output version

mpOpenAPI-4.0 can output documentation in either OpenAPI 3.1 (the default) or OpenAPI 3.0 format.

Configure the OpenAPI output format using the mpOpenAPI.openAPIVersion attribute:

Example: configure output in OpenAPI 3.0 format:

<mpOpenAPI openAPIVersion="3.0" />

Configure which applications and modules are included in the OpenAPI documentation

The applications to be included can be controlled using these subelements of <mpOpenAPI>:

<includeApplication>
<excludeApplication>
<includeModule>
<excludeModule>

Additional detail and examples to be added here

These configuration options are available in mpOpenAPI-2.0 and later, starting with 24.0.0.12.

By default:

mpOpenAPI-4.0 includes all deployed applications
earlier versions include only the first module of the first deployed application

Configure the `info` section of the OpenAPI documentation

The info section can be overridden using the <info> subelement of <mpOpenAPI>.

<mpOpenAPI>
  <info title="My API"
        version="1.0"
        description="An example API used for documentation"/>
</mpOpenAPI>

This is often used when including multiple applications which each have a different info section.

Updates to existing topics

To update existing topics, specify a link to the topics that are affected. Include a copy of the current text and the exact text to which it will change. For example: Change ABC to XYZ

We're making quite large changes to the OpenAPI documentation, so consider these first drafts.

Changes to https://openliberty.io/docs/latest/documentation-openapi.html

ADD Supported OpenAPI versions (after "The design-first approach")

The MicroProfile OpenAPI feature generates structured documentation according to the OpenAPI specification, with each new version of the OpenAPI specification updating the format of the structured documentation. Different versions of the MicroProfile OpenAPI support different versions of the OpenAPI specification.

|=== |Feature | OpenAPI versions supported

|mpOpenAPI-4.0 | 3.1, 3.0

|mpOpenAPI-3.1 | 3.0

|mpOpenAPI-3.0 | 3.0

|mpOpenAPI-2.0 | 3.0

|mpOpenAPI-1.1 | 3.0

|mpOpenAPI-1.0 | 3.0 |===

When using a feature which supports more than one version of the OpenAPI specification, you can switch between them with configuration. You might need to do this if you or your end users use tools or libraries to consume the documentation which don't yet support a newer version of the OpenAPI specification.

Example: select OpenAPI v3.0 when using mpOpenAPI-4.0

<mpOpenAPI openAPIVersion="3.0"/>

REPLACE Multiple application and multi-module application support with MicroProfile OpenAPI

When multiple applications, or applications with more than one web module are deployed to the same Open Liberty server, the behaviour differs between MicroProfile OpenAPI feature versions.

|=== |Feature |Behavior

|mpOpenAPI-4.0 |By default, all deployed applications and modules are included in the structured documentation. This can changed through configuration.

|mpOpenAPI-2.0 to mpOpenAPI-3.1 |By default, only the first web module of the first application deployed is included in the structured documentation. This can be changed through configuration.

|mpOpenAPI-1.0 to mpOpenAPI-1.1 |Only the first web module of the first application deployed is included in the structured documentation. This cannot be changed. |===

For MicroProfile OpenAPI 2.0 and later, the applications and modules included in the structured documentation can be controlled using the <includeApplication>, <excludeApplication>, <includeModule> and <excludeModule> elements within the [<mpOpenAPI> configuration element].

For example, to include all of the deployed applications and modules in the generated structured documentation when using mpOpenAPI-2.0, add the following configuration to your server.xml.

<mpOpenAPI>
  <includeApplication>all</includeApplication>
</mpOpenAPI>

For example, to include all of the deployed applications and modules except for the "admin" module of "application1", add the following configuration to your server.xml:

<mpOpenAPI>
  <includeApplication>all</includeApplication>
  <excludeModule>application1/admin</excludeModule>
</mpOpenAPI>

Notes:

The application name is the value of the name attribute when the application is deployed in server.xml using <application>, <webApplication> or <enterpriseApplication>:
```
<webApplication name="application1" location="application1-v1.war" />
```
If the application is deployed in dropins or the name attribute is not specified, the name defaults to the archive filename with the extension removed.
The module name is the name specified in the web module's web.xml. If there is no web.xml or it does not specify a name, it defaults to the module filename with the extension removed.

It is also possible to override the info section of the OpenAPI document using configuration:

<mpOpenAPI>
  <info title="Example API"
        version="1.0"
        description="This is an example API"/>
</mpOpenAPI>

This may be useful when documenting multiple modules or applications because the info section would otherwise be replaced with a standard one that just says that the documentation from several modules was merged.

Configuring multiple application and multi-module support using MicroProfile Config

The modules and applications to be included in the structured documentation can also be configured using MicroProfile Config with the following limitations:

If conflicting configuration is found in server.xml, the MP Config configuration will be ignored
The configuration properties must be set using a configuration source that's not specific to an application, for example using system properties, environment variables or server.xml <variable> elements.

The following table lists MicroProfile Config properties that can be specified to configure which modules or applications are included in the generated OpenAPI documentation.

<<existing table with "default value" column removed>>

default behaviour is now different from version to version and explained earlier

Notes:

When configuring multiple application and multi-module support using MicroProfile Config, the application name is the name from the application's deployment descriptor (application.xml or web.xml). If there is no deployment descriptor or it does not specify a name, the name is the application archive filename with the extension removed.
The module name is the same as for server.xml configuration above.

Changes to existing feature pages (`mpOpenAPI-2.0` - `3.1`)

REPLACE Configure OpenAPI documentation for a multi-module application

By default only the first module of the first application deployed is included in the OpenAPI documentation, but you can configure the Microprofile OpenAPI feature to merge 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 with 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="sample_app_support@example.com"
        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 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

For more information, see [Multiple application and multi-module application support with MicroProfile OpenAPI]

Create a new topic

To create a topic, specify a first draft of the topic that you want added and the section in the navigation where the topic should go.

New feature page for `mpOpenAPI-4.0`

Copy from mpOpenAPI-3.1 but...

REPLACE Configure OpenAPI documentation for a multi-module application

Note this example is similar but not identical to the example for 2.0-3.1

By default all deployed applications and modules are included in the OpenAPI documentation, but you can configure which applications and modules should be included.

For example, the following configuration is for the sample_app application which consists of an EAR file with 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="sample_app_support@example.com"
        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

For more information, see [Multiple application and multi-module application support with MicroProfile OpenAPI]

OpenLiberty / docs