mpOpenApi-2.0 support for multiple applications and web modules

[Azquelt]

Documentation for OpenLiberty/open-liberty#16628

This feature doesn't currently have a release date but we hope to beta it soon. When it is ready, we'll need to add documentation for how users enable and configure multi-module support.

As a starting point, I propose adding the following text to API documentation with OpenAPI.

Multiple-Application support (mpOpenApi-2.0) (Beta)

By default, only the first web module of the first application deployed has OpenAPI documentation generated for it. The MicroProfile OpenAPI 2.0 feature provides configuration properties to select which applications and web modules should have OpenAPI documentation generated and to set the info section of the final OpenAPI document. If more than one web module is selected, an OpenAPI document is generated for each module and then they are merged to create a single OpenAPI document.

The following MicroProfile Config properties can be used to configure which applications should have OpenAPI documentation generated:

• mp.openapi.extensions.liberty.merged.include
  • Configures which applications should have OpenAPI documentation generated. The value must be one of
    • all - includes all applications
    • first - includes only the first web module of the first application deployed (this is the default)
    • a comma separated list of <application name> and <application name>/<module name> - includes the named applications and modules
• mp.openapi.extensions.liberty.merged.exclude
  • Overrides the includeconfig property, indicating which applications should not have OpenAPI documentation generated. The value must be one of:
    • none - excludes no applications (this is the default)
    • a comma separated list of <application name> and <application name>/<module name> - excludes the named applications and modules
• mp.openapi.extensions.liberty.merged.info
  • The value must be a valid OpenAPI Info section in JSON format.
  • If set, the info section in the final OpenAPI document is replaced with the value of this config property.
  • This replacement is done after any merging has taken place

[dmuelle]

Hi @Azquelt - I have a draft ready for review this update: https://draft-openlibertyio.mybluemix.net/docs/21.0.0.12/documentation-openapi.html#_multiple_application_and_multi_module_application_support_with_microprofile_openapi

To match what they did in the beta post, I defined the properties in table format. I also took a stab at adding an example of how you would specify them. If they aren't helpful/plausible I can revise or remove them.

When you have a chance, let me know if any further edits are needed. If not, you can add the technical reviewed label to this issue and the update will publish with the 21.0.0.12 docs release. Thanks

[dmuelle]

I've just reviewed your related messages in https://github.com/OpenLiberty/open-liberty/pull/19218#pullrequestreview-796030139 and am wondering about the suggested action:

"...configure the mpOpenApi-2.0 feature to exclude one of the modules."

I hadn't thought of specifying MP config properties as being "configuring the OpenAPI-2.0 feature" and I guess its splitting hairs to say whether it is, but it makes me wonder the examples I added (or some version of them) wouldn't be better on the MP OpenAPI feature page. I hadn't thought of it earlier because I was thinking of the properties from the MP Config perspective, but someone might go looking at the OPenAPI feature page to find out how to configure multi-module support

[Azquelt]

Configuration is odd because we currently have a big reference for everything that's supported in server.xml, but newer microprofile features are mostly using MP Config for configuration.

IMO, configuration should be a standard section on every feature page, along with links to the javadoc for any APIs provided by the feature, links to any specifications it implements and details of any endpoints it provides.

[dmuelle]

I agree- the problem is with 105 features and counting, we don't currently have the development resources to generate that info programmatically or the ID resources to write and maintain it manually. So we're reduced to adding configuration examples as we go. But it's a good point- that would substantially improve the value of the feature pages. And for the MP features, I think the relevant MP config properties should be part of the baseline documentation for each feature. I'll add these to the MP OpenAPI feature page.

[Azquelt]

I've checked your draft and I can't see any problems.

However, Emily since asked me to document the merging behaviour. Would you like me to add that to this issue or open a new one?

[Azquelt]

This is the additional information which needs to be included. I think this section can be added to the end of the page (after "Configure OpenAPI documentation for a multi-module application")

Resolving conflicts when merging

When OpenAPI documentation from multiple modules needs to be merged together, liberty applies the following rules to resolve conflicts between the OpenAPI documents being merged:

• Within each document, if there are no servers or if all server URLs in the document end with the context root, the context root is removed from each server URL and prepended to each path.
• If the same path is now declared in more than one document, a warning is logged and all but one of the clashing documents is excluded from the merged documentation.
• If the same extension name is declared at the top level of more than one document with different values, a warning is logged and all but one of the clashing documents is excluded from the merged documentation.
• If the servers section at the top level is not the same across all documents, each server is copied under each path that it applies to and is removed from the top level.
• Component names are made unique by adding a number to the end of them where necessary. References to the component name are updated.
• Operation IDs are made unique by adding a number to the end of them where necessary. References to the operation ID are updated.
• If the info section is not identical across all documents, it is replaced by a standard info section saying that the documentation from several modules has been merged.
• If the security requirements section at the top level is not the same across all documents, the security requirements are copied under each path that they apply to.
• If the external documentation section is not the same across all documents, it is removed.

[dmuelle]

Hi @Azquelt - I've updated the draft with this information and made a few minor edits:

https://draft-openlibertyio.mybluemix.net/docs/21.0.0.12/documentation-openapi.html#multi-module

let me know if any further edits are needed. If not, you can add the technical reviewed label to this issue and the update will publish with the 21.0.0.12 docs release. Thanks

[Azquelt]

Thanks @dmuelle, that's really good. Just a few small changes.

each server is removed from the top level and copied under the path that it applies to.

Change "the path" to either "each path" or "the paths". (A server declared at the top level of the document applies to all paths within the document which don't specify a different list of servers, so we expect it to apply to multiple paths)

If the top-level security scheme section is not the same across all documents, the security requirements are copied under each path that they apply to.

This should be "If the top-level security section is not the same across all documents, the security requirements are copied under each operation that they apply to."

The top level OpenAPI object contains a security field which contains an array of security requirements. These are separate to the Security Schemes which can be declared as Components.

The security section can be overridden at the Operation level (not the path level as I originally wrote).

If the external documentation section...

Let's change this to "If the externalDocs section..." for consistency with the previous bullet points. (externalDocs is the name of the field, it contains the links to External Documentation)

[dmuelle]

Thanks for reviewing @Azquelt. I've made these changes to the draft:

https://draft-openlibertyio.mybluemix.net/docs/21.0.0.12/documentation-openapi.html#multi-module

• [x] Change "the path" to either "each path" or "the paths".
• [x] This should be "If the top-level security section is not the same across all documents...
• [x] change this to "If the externalDocs section..

Let me know if you see anything else that needs an edit. If not, you can add the technical reviewed label to this issue to sign off.

[Azquelt]

security requirements are copied under each path that they apply to

security requirements are copied under each operation that they apply to

Sorry, this was a mistake in my original comment.

Everything else is good.

[dmuelle]

I've added that change:

https://draft-openlibertyio.mybluemix.net/docs/21.0.0.12/documentation-openapi.html

If everything else looks good, you can add the technical reviewed label to sign off. If anything further is needed, just let me know. Thanks

[Azquelt]

All looks good, thanks @dmuelle

[Azquelt]

Release of this feature has been moved back to 22.0.0.1.

[ramkumar-k-9286]

Peer Review

The two main approaches to generate an OpenAPI document are the code-first approach and the design-first approach. ---> The two main approaches to generating an OpenAPI document are the code-first approach and the design-first approach.

The default format of the generated document is yaml, but documents can also be provided in JSON format. The following OpenAPI document is generated in yaml format from the OpenAPI annotations in the previous the example. ---> The default format of the generated document is YAML, but documents can also be provided in JSON format. The following OpenAPI document is generated in YAML format from the OpenAPI annotations in the previous example.

description: The registration of the car to be added to the inventory. ---> description: The registration of the car is to be added to the inventory.

For more information, see the MicroProfile OpenAPI Javadoc for the annotations that are available. ---> For more information, see the MicroProfile OpenAPI Javadoc for the available annotations.

An alternative approach is to design the REST API in an editor, such as the Swagger editor, before you write any code. ---> An alternative approach is to design the REST API in an editor, such as the Swagger editor before you write any code.

You can write this API design in yaml or JSON format and place it in the META-INF directory of your application. ---> You can write this API design in YAML or JSON format and place it in the META-INF directory of your application.

The code first and design-first approaches are not mutually exclusive. ---> The code-first and design-first approaches are not mutually exclusive.

For more information, see Using pregenerated OpenAPI documents. ---> For more information, see Using pre-generated OpenAPI documents.

The OpenAPI document can be viewed in a browser by using the /openapi endpoint. ---> The OpenAPI document can be viewed in a browser by using the /openAPI endpoint.

These properties are available when you enable the MicroProfile OpenAPI feature, version 2.0 and later. ---> These properties are available when you enable the MicroProfile OpenAPI feature, version 2.0, and later.

[Azquelt]

A few counter suggestions:

description: The registration of the car to be added to the inventory. ---> description: The registration of the car is to be added to the inventory.

This description applies to the registration parameter, so I'd put one of the following: The registration of the car to be added to the inventory. The registration of the car which is to be added to the inventory.

An alternative approach is to design the REST API in an editor, such as the Swagger editor, before you write any code. ---> An alternative approach is to design the REST API in an editor, such as the Swagger editor before you write any code.

I think the original is better here. The approach is to design the REST API in an editor before you write any code. Using the swagger editor to do this is just an example and keeping that text between two commas makes this clear.

For more information, see Using pregenerated OpenAPI documents. ---> For more information, see Using pre-generated OpenAPI documents.

This is a link to a section in a different document. I think we should use the name of the section as it is in that document, even if your rewriting of it is better.

The OpenAPI document can be viewed in a browser by using the /openapi endpoint. ---> The OpenAPI document can be viewed in a browser by using the /openAPI endpoint.

This change is incorrect. The endpoint is /openapi, not /openAPI. I'm not actually sure whether the server is case-sensitive when looking up this endpoint, but the endpoint is specified as /openapi.

[Azquelt]

I also noticed the following part which doesn't make sense and I must have missed when I reviewed this before:

By default, OpenAPI documentation is generated for only the first web module of the first application in your EAR file.

An EAR always contains one application, so saying "the first application in your EAR file" doesn't make sense.

What actually happens is that it tries to generate OpenAPI documentation for each module of each deployed application* in turn, until it finds one for which it can generate an OpenAPI document (usually this is the first module with REST endpoints), then it ignores the others.

If the documented application is later removed, the server will again try to generate OpenAPI documentation for each of the modules of the remaining applications in turn until it finds one for which it can generate an OpenAPI document.

I think the easiest thing is to say one of the following:

• "By default, OpenAPI documentation is generated for only the first web module of the first application deployed on the server".
• "By default, OpenAPI documentation is generated for only one of the web modules deployed on the server".

Neither of these quite describe the nuance of exactly what the server does, but I think both describe what the user will see happen well enough.

* an application will usually be a .war or a .ear file. A .war is always a single web module. An .ear may contain multiple web modules.

[dmuelle]

Thanks @Azquelt @ramkumar-k-9286 , I've updated the draft:

https://draft-openlibertyio.mybluemix.net/docs/latest/documentation-openapi.html

I made Andrew's requested change to the default behavior statement and Ram's requested changes, with the following exceptions:

The two main approaches to generating an OpenAPI document are the code-first approach and the design-first approach. it's a minor difference but i think the infinitive is stronger than the gerund in this case so left as is.

description: The registration of the car is to be added to the inventory. An alternative approach is to design the REST API in an editor, such as the Swagger editor before you write any code. For more information, see Using pre-generated OpenAPI documents. The OpenAPI document can be viewed in a browser by using the /openAPI endpoint. These properties are available when you enable the MicroProfile OpenAPI feature, version 2.0, and later. agreed with Andrews counter suggestions and left these as they were

[ramkumar-k-9286]

Peer Review

MicroProfile OpenAPI facilitates this communication by generating human and machine-readable documentation on a simple interface that doesn’t require access to the source code. ---> MicroProfile OpenAPI facilitates this communication by generating human and machine-readable documentation on a simple interface that does not require access to the source code.

The default format of the generated document is YAML, but documents can also be provided in JSON format. The following OpenAPI document is generated in YAML format from the OpenAPI annotations in the previous the example. ---> The default format of the generated document is YAML, but documents can also be provided in JSON format. The following OpenAPI document is generated in YAML format from the OpenAPI annotations in the previous example.

If the same extension name is declared with different values at the top level of more than one document, a warning is logged. ----> Not sure about this - top being picked up by acrolinx for non-compliance with IBM accessibility standards

If the top-level servers section is not identical across all documents, each server is removed from the top level and copied under the paths that it applies to. ---> Not sure about this - top being picked up by acrolinx for non-compliance with IBM accessibility standards

I remember you telling me that add links to a topic the first time it is mentioned ---> I see the links for The MicroProfile OpenAPI feature being provided multiple times. -> please confirm.

[dmuelle]

Draft updated:

https://docs-draft-openlibertyio.mybluemix.net/docs/22.0.0.1/documentation-openapi.html

made all changes except for the following:

MicroProfile OpenAPI facilitates this communication by generating human and machine-readable documentation on a simple interface that does not require access to the source code. contractions are ok

In this context, "top-level" refers to hierarchy rather than spatial direction. It's also a commonly used term in OpenAPI documentation

I removed one redundant link to the feature, but kept the second link as it refers to specific examples on the feature page.

[ramkumar-k-9286]

LGTM.

Adding the `Peer Reviewed' label.

Regards Ramkumar

[dmuelle]

Topic is on vNExt and will publish with 22.0.0.1 on 1/18. Closing this issue