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.

[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

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

Regards,
Ramkumar.

[dmuelle]

Peer review

• We should add an anchor list of the sections after the intro to the topic
• in general, config examples should be on the feature page, not in a concept topic

Supported OpenAPI versions

• Theres some redundancy in this table- why not just make it two rows, one for mpOpenAPI-4.0, and nther that is just "mpOpenAPI-3.1 and earlier"

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 behavior differs between MicroProfile OpenAPI feature versions
--->
When multiple applications or applications with more than one web module are deployed to the same Open Liberty server, the structured documentation differs depending on which MicroProfile OpenAPI feature version you use.

This can changed through configuration. --> rewrite this sentence and similar ones so that it has a subject other than "this"

Configuring multiple application and multi-module support

Configure using the server.xml file: This method involves configuring your server to deploy multiple applications by specifying the applications and modules within the server.xml file.

This is confusing- are you configuring API docs or the application deployment? Does this option require certain app definitions in the server.xml? Why might someone choose this option over the "easy" alternative of using MP config?

These examples already exist on the feature page- we should just point there. If the examples on the feature page arent sufficient, we can rework them

The module name defaults to the filename with the extension removed.

Which file name?

• Is the example about info only relevant when you configure in server.xml? Or does it also work if you otherwise configure in MP Config? Does the info element also apply if you are documenting a single application and want to overide the info section?

Configure using the MicroProfile Config

---> Configure using MicroProfile Config properties

For example, you can use system properties, environment variables, or variable elements in the server.xml file.

this needs more detail- system properties can be set in jvm.properties or bootstrap.properties file. Environment variables in server.env. As written it looks like all are set in server.xml

[Azquelt]

Hi @dmuelle, I see your feedback and I've talked to @ramkumar-k-9286 about the proposed changes and I have a couple of concerns.

Firstly, I need to let you know that having the MicroProfile Config options for this feature was a mistake. It's a problem for a couple of reasons:

• It's server-wide configuration, not application specific configuration, and server configuration should all be in server.xml
• Because it's configuring the server and not an application, the config properties can't be provided in a microprofile-config.properties file within the application. Config properties within an application only apply to that application. This is confusing for users, particularly if they're only deploying one application, which is pretty common for users of MicroProfile.

The only reason the MicroProfile Config options exist today is for backward compatibility so this page should push people towards configuration via server.xml.

in general, config examples should be on the feature page, not in a concept topic

I'm worried that if we remove all the config examples from this page, the part about configuration via server.xml becomes one line and the part about MP Config properties is several paragraphs and a big table, which makes MP Config seem like the more important option.

I'm not against moving the examples, but I would want to ensure that the page pushes people towards configuring this feature with server.xml.

Within the examples, I think the most commonly used one will be how to include all applications on mpOpenAPI-2.0 - -3.1:

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

Outside of this, I don't expect many users to need to use the include/exclude configuration at all, so this example should be easy to find, even though it doesn't apply to mpOpenAPI-4.0 because that version defaults to including everything.

Naming applications and modules

The text "Naming applications and modules" has been made into a header again (previously it was "Notes:" for the preceding examples).

If this has to be a header, you need another header at this level before the next paragraph describing the use of <info>, otherwise it looks like those paragraphs are part of "Naming applications and modules", which they aren't. You might want another header for the earlier examples as well for consistency.

Theres some redundancy in this table- why not just make it two rows, one for mpOpenAPI-4.0, and nther that is just "mpOpenAPI-3.1 and earlier"

This is true - I deliberately wrote the table in a redundant way because when I talk about this feature, it confuses everyone that MP OpenAPI 4.0 supports OpenAPI 3.1. By making the table redundant like this, I think it makes it more clear that we've been using OpenAPI 3.0 in every version since MP OpenAPI 1.0, and the OpenAPI version is not linked in any way to the feature version. I'm happy to be overruled on this if you think a concise table would be more helpful, but I wanted to communicate why I wrote it like that.

[dmuelle]

Thanks @Azquelt for this context. A few thoughts -

If the mpconfig is only for backward compatibility- we already document these properties on the MicroProfile Config properties page. Instead of documenting them explicitly here, why not just have a sentence that points to that table.

Keep in mind that users of earlier versions can still select those versions in the doc and see all the config examples we've previously had relevant to those versions. We can also emphasize server.xml config as the best option, mp config just for compatibility with earlier versions

Then we can structure the examples on the feature pages in a logical way, with descriptive headings, and only show the examples that are relevant to each particular version.

For the supported versions table- we can restore the previous table.
Might just be a matter of personal preference but I found myself scanning the table trying to figure out what I was missing. mAybe even just saying something like
"All MicroProfile OpenAPI versions support OpenAPI 3.0, while only versions 4.0 and later support OpenAPI 3.1."
I know there is no "and later" yet, but it will save the statement from going stale once there are

[Azquelt]

I'm not happy with how the docs here have turned out and so I'm removing the developer reviewed tag. I think this is reasonable given how much has changed since I approved them.

Here are the issues with the current docs:

1. Previously, pretty much everything you needed to know about configuring liberty for OpenAPI was on the API documentation with OpenAPI. Now we have information scattered across the following pages:

   • The API documentation with OpenAPI page has the two conceptual approaches to documenting REST interfaces, which OpenAPI versions are supported and "support for multiple applications and multi-module applications" which includes the default behaviour, pointers to configuration with server.xml and MicroProfile Config Properties, that server.xml overrides MP Config, and how the names of apps and modules are interpreted for MP Config.
   • The mpOpenAPI-x.x feature pages which has configuration examples and information about the naming of applications and modules referenced in server.xml.
   • The <mpConfig> configuration element page which has reference information about the server.xml config elements. It does include information about how to reference applications and modules by name, but unfortunately all the info is condensed into one dense paragraph per attribute because we can't have formatting in the description or supplemental info on that page.
   • The MP Config Properties page lists the inclusion and exclusion properties but does not have enough information for the user to actually use them.

   There are now too many places that the user has to look for the necessary information and they're not linked together well. On the multi-module support in particular, do we really have to have the introductory explanation on one page, the examples on another and the reference for the config on two more separate pages? If we're going to do that then we need to ensure they're all linked together really well.

   As an end user, I can understand having the reference documentation separate, but I would expect the higher-level documentation to include examples. Where can I put an explanation of what you can configure with this feature and how to do it?

2. The examples on the feature page are not great and are hard to read. I will rewrite these.

3. The information about the naming of modules and applications when referenced from config needs to be next to the config elements or properties that do that referencing. The MP Config information is on a different page. The server.xml information is on the right page, but it's squashed into a box in a table.

Now, I'll be honest, I just dumped out of my brain everything I know needs to be documented for this feature and arranged it into what I thought was a sensible order for someone to read. If we have a strategy for how our docs are supposed to fit together that says things like "no examples on concept pages", can you link me to that so I can try to arrange what I know needs to be there into something resembling a sensible order that fits within that framework?

[dmuelle]

Hi Andrew- I've updated the draft to restore the content that was moved out of the topic. We need to align on something at least for the 240012 release and the doc freeze is tomorrow. Hopefully this is closer to what you were thinking:

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

In general, the OL docs strategy is to put feature-related configuration on the feature pages, in concise examples with descriptive headings, and to avoid edge cases or multiple equivalent ways of doing the same thing, so the majority users can quickly find the information that they need to accomplish a specific goal.

Concept topics help users understand the intention and logic of a given feature, then they decide what they want to configure and select the corresponding resource. Users shouldn't need to click between all the possible combinations of topics. For instance, I dont think the user should need the full OpenAPI configuration element reference table to learn how to configure their multi-module OpenAPI documentation, but it might be useful if they are looking at a server.xml file and then want to quickly look up what a certain element or attribute does. This of course is the ideal and there are plenty of exceptions :)

The guiding principle is really progressive disclosure- insofar as possible, only show the user the information they need to accomplish their goal. No one user needs all the possible options, so when you put everything into one topic, you often give everyone more things they have to ignore and make the whole task seem more complicated than it actually is. In general, users don't want to know "What is everything I can possibly do with x feature?" but instead "How can I quickly get x job done?"

Applied in this case, users who want to configure multimodule documentation would read the basic conceptual details, then self-select whether they want to see more detailed content about the specific feature version or config method they choose, instead of having to parse through the whole range of details about every option. Then they click through to the version of the feature they are using for a detailed configuration example that is specific to that version and its defaults. It might be that the previous draft was not serving this goal very well, but that's the logic behind it.

[Azquelt]

Thanks David, I think this is much better for now, and we can look to improve it after this release so that it better matches the desired structure.

I noticed a few typos:

• on https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/documentation-openapi.html#multi-module
  • under "Including and excluding applications and modules from OpenAPI documentation", the link to the MP Config section is broken.
  • under "Configure application or module documentation by using MicroProfile Config properties", the second paragraph begins "WHen"