Documentation: MicroProfile OpenAPI 4.0

[Azquelt]

Feature epic details

• For the title of this issue, type: Documentation, Development epic name
• Link to development epic: MP70: Implement MicroProfile OpenAPI 4.0 open-liberty#27311
• Target GA release: 24.0.0.12

Operating systems

Does the documentation apply to all operating systems?

• 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="[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 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="[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

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

[Azquelt]

@ramkumar-k-9286 I've updated the issue with an initial draft of the new documentation sections needed for this release.

Let me know if anything isn't clear (sorry it's always a bit of a mess writing asciidoc with headings in github issues which use markdown and already have headings).

[ramkumar-k-9286]

Hi Andrew @Azquelt

Draft documents ready:

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/documentation-openapi.html

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/mpOpenAPI-2.0.html

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/mpOpenAPI-3.0.html

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/mpOpenAPI-3.1.html

Note: I have added the mpOpenAPI-4.0 - content in the mpOpenAPI-3.1 file. ( Though I have already created the file, you would not be able to see it on a draft site.) You can review and add comments and I will incorporate them into the new file.

Please add the Developer Reviewed label if you are satisfied with the changes.

Regards,
Ramkumar

CC @dmuelle

[Azquelt]

• Supported OpenAPI versions
  • Can you make the columns less wide. I think the table will always take up the full width but it'll be easier to read if the first column is much narrower.
• Multiple application and multi-module application support with MicroProfile OpenAPI
  • Table of features and behaviour
    • please make the left column narrower (as above)
  • Configuring with <includeApplication> etc. in server.xml
    • We need to link to reference doc for the <mpOpenAPI> element in this section.
      Could we change "the configuration element" into a link to https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/config/mpOpenAPI.html ?
    • I'm debating whether this section needs its own header "Configuring multiple application and multi-module support using server.xml" (mirroring the MP Config header later in the doc). What do you think?
    • I think "Key Points" is the wrong phrase to use here. The bullets are not a summary of the key points that the user has to be aware of, it's supplementary detail to the examples preceding it and the <mpOpenAPI> reference doc. I also think it's shouldn't be a header.
    • In the Notes / Key Points section, please make the example and the following text part of the bullet (as it is in this issue). Hopefully this will be enough to stop the Notes merging in with the following paragraph about overriding the info section.
• Configuring multiple application and multi-module support using MicroProfile Config
  • Remove "The default behavior varies between versions and has been explained earlier."
  • Change "Key Points" back to "Notes" and make it not a header (same reasoning as above).

[ramkumar-k-9286]

hi @Azquelt

Suggested changes have been made. please have a look at the draft links.

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/documentation-openapi.html

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/mpOpenAPI-3.1.html

Note: I have added the mpOpenAPI-4.0 - content in the mpOpenAPI-3.1 file. ( Though I have already created the file, you would not be able to see it on a draft site.) You can review and add comments and I will incorporate them into the new file.

Please add the Developer Reviewed label if you are satisfied with the changes.

Regards,
Ramkumar

CC @dmuelle

[Azquelt]

Thanks @ramkumar-k-9286, only a few more changes:

In https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/documentation-openapi.html

• The paragraph starting "You can also override the info section" should not be part of the preceding bullet list.

In https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/mpOpenAPI-3.1.html

• There are two "Examples" headings. There should only be one heading with the two examples under it.

[ramkumar-k-9286]

Hi @Azquelt

I made the suggested correction.

Draft link: https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/documentation-openapi.html

The examples heading - I noticed that it appears on all versions - 3.1, 3.0, 2.0 - let me check with David and get back to you on this.

Regards,
Ramkumar.