Davids edits

#7654

modules/ROOT/pages/documentation-openapi.adoc

@@ -156,36 +156,53 @@ The MicroProfile OpenAPI feature generates structured documentation based on the
 |===
 
 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 end users use tools or libraries that don't yet support a newer version of the OpenAPI specification.
-
 For more information, see link:/docs/latest/reference/feature/mpOpenAPI-4.0.html#apiversion[Selecting the OpenAPI specification version].
 
 
 [#multi-module]
 == 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 structured documentation differs depending on which MicroProfile OpenAPI feature version you use.
+When multiple applications or an application with more than one web module are deployed to the same Open Liberty runtime, the structured documentation differs depending on which MicroProfile OpenAPI feature version you use.
 
 .Multiple application and multi-module application support with MicroProfile OpenAPI
 [cols="1,2", options="header"]
 |===
 |Feature |Default behavior
 
 |`mpOpenAPI-4.0`
-|All deployed applications and modules are included in the structured documentation, and the behavior can be modified through configuration.
+|All deployed applications and modules are included in the structured documentation. You can modify this behavior through configuration.
 
 |`mpOpenAPI-2.0` to `mpOpenAPI-3.1`
-|Only the first web module of the first deployed application is included in the structured documentation, but the behavior can be modified through configuration.
+|Only the first web module of the first deployed application is included in the structured documentation. You can modify this behavior through configuration.
 
 |`mpOpenAPI-1.0` to `mpOpenAPI-1.1`
-|Only the first web module of the first deployed application is included in the structured documentation, and this behavior cannot be modified.
+|Only the first web module of the first deployed application is included in the structured documentation. This behavior cannot be modified.
 |===
 
 [#conf-mm-supprt]
-== Configuring multiple application and multi-module API documentation
+== Including and excluding applications and modules from OpenAPI documentation
+
+You can configure which applications or modules are included in your OpenAPI documentation either by setting elements in your server.xml file or by specifying MicroProfile Config properties. For most scenarios, 'server.xml` configuration is preferred and MicroProfile Config properties are recommended only for compatibility with earlier versions of MicroProfile OpenAPI that are already using these properties.
+
+Configure application or module documentation by using the `server.xml` file::
+You can control the inclusion and exclusion of applications and modules in the OpenAPI documentation by configuring the `mpOpenAPI` configuration element in your `server.xml` file.
++
+In MicroProfile OpenAPI 4.0 and later, all applications and modules are included by default. To exclude certain applications or modules, see link:/docs/latest/reference/feature/mpOpenAPI-4.0.html#_configure_openapi_documentation_for_a_multi_module_application[MicroProfile 4.0: Configure OpenAPI documentation for a multi-module application].
++
+In MicroProfile MicroProfile OpenAPI 2.0-.31, only the first web module of the first deployed application is included in the structured documentation. To include or exclude applications or modules, see link:/docs/latest/reference/feature/mpOpenAPI-3.0.html#_configure_openapi_documentation_for_a_multi_module_application[MicroProfile 3.0: Configure OpenAPI documentation for a multi-module application]
+
+Configure application or module documentation by using MicroProfile Config properties::
+MicroProfile Config provides properties to manage which applications and modules are included in the generated OpenAPI documentation. This option is recommended only for compatibility with applications that already use MicroProfile config to include or exclude modules or applications fro the API documentation. Newer configurations can instead use the `server.xml` file, as previously described.
++
+- You must configure properties by using sources that apply to the entire server, such as the `jvm.properties`, `server.env`, or the environment variables.
+- When you configure support for multiple applications and multi-module environments by using MicroProfile Config, the application name is determined from the application's deployment descriptor (`application.xml` or `web.xml`). If the deployment descriptor is missing or does not specify a name, the application name defaults to the application archive file name without the file extension. Similarly, the module name is specified in the web module `web.xml` file. If the `web.xml` file  does not exist or does not specify a name, the module name defaults to the file name without the file extension.
+- Any configuration that is defined in the `server.xml` file to include or exclude modules and applications takes precedence over configuration that is set through MicroProfile Config.
++
+For more information, see the xref:reference:config/mpOpenAPI.adoc[MicroProfile Config properties for MicroProfile OpenAPI].
 
-Open Liberty offers two main ways to configure support for multiple applications and multi-module projects.
 
-=== Configure by using the `server.xml` file
+
+===
 
 Customize the structured API documentation that is generated for your applications by configuring the link:/docs/latest/reference/feature/mpOpenAPI-4.0.html#_configure_openapi_documentation_for_a_multi_module_application[server.xml] file. Use the following elements within the `mpOpenAPI` configuration to control the inclusion and exclusion of applications and modules in the OpenAPI documentation:
 
@@ -204,11 +221,10 @@ For more information, see the feature:mpOpenAPI[MicroProfile OpenAPI 4.0] featur
 MicroProfile Config provides a way to manage which applications and modules are included in the generated OpenAPI documentation by specifying configuration properties. Use these properties to define inclusion and exclusion rules and to customize the `info` section of the final OpenAPI document.
 
 - This method is suitable for dynamic setups because it allows changes to be made without directly modifying the `server.xml` file.
-- When both methods are used, configurations that are defined in the `server.xml` file take precedence over the ones set through MicroProfile Config.
-- Properties must be configured by using sources that apply to the entire server, such as the `jvm.properties`, `server.env`, or the environment variables.
+
 - MicroProfile Config options are compatible only with versions 3.0 and earlier.
 
-When you configure support for multiple applications and multi-module environments by using MicroProfile Config, the application and module names are determined based on specific rules.
+, the application and module names are determined based on specific rules.
 
 - **Application name**: The application name is determined from the application's deployment descriptor (`application.xml` or `web.xml`). If the deployment descriptor is missing or does not specify a name, the application name defaults to the application archive filename with the file extension removed.
 - **Module name**: The module name is determined by using the same rules as described for the `server.xml` configuration.

modules/reference/pages/feature/mpOpenAPI-3.0/examples.adoc

@@ -1,9 +1,9 @@
 
 === Configure OpenAPI documentation for a multi-module application
 
-// This example only applies to 2.0 forward, and so the file and directory must be manually copied and applied to any new versions. Copy the directory and file and change the directory name to reflect the new feature version, for example `mpOpenAPI-3.2`.
+// This example applies only to versions 2.0-3.1.
 
-By default, only the first module of the first deployed application is included in the OpenAPI documentation. However, you can configure the MicroProfile OpenAPI feature to merge the OpenAPI documentation for multiple applications or modules into a single document.
+Only the first module of the first deployed application is included in the OpenAPI documentation by default. However, you can configure the MicroProfile OpenAPI feature to merge the 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 containing five web modules.
 
@@ -26,13 +26,13 @@ For example, the following configuration is for the `sample_app` application, wh
 </mpOpenAPI>
 ----
 
-- The `<includeApplication>` element specifies that all applications are included in the final OpenAPI document.
+- 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 `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.
+- The `info` element sets the info section for the final OpenAPI document, which documents web modules 1, 2, and 4.
 
-=== Naming applications and modules   
+==== 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:
 +
@@ -45,9 +45,11 @@ If the application is deployed in the `dropins` directory or if the `name` attri
 +
 - The module name is specified in the web module's `web.xml` file. If there is no `web.xml` file or if it does not specify a name, the module name defaults to the filename with the extension removed.
 
+For more information, see xref:ROOT:documentation-openapi.adoc#multi-module[Multiple application and multi-module application support with MicroProfile OpenAPI].
+
 === Override the info section in the OpenAPI document
 
-You can also override the `info` section of the OpenAPI document using the following configuration:
+You can override the `info` section of the OpenAPI document specifying the `info` element within the `mpOpenAPI` element:
 
 [source,xml]
 ----
@@ -58,6 +60,4 @@ You can also override the `info` section of the OpenAPI document using the follo
 </mpOpenAPI>
 ----
 
-Overriding the `info` section is useful for documenting multiple modules or applications. Without an override, the `info` section can be replaced with a standard version which indicates that documentation from several modules was merged.
-
-For more information, see xref:ROOT:documentation-openapi.adoc#multi-module[Multiple application and multi-module application support with MicroProfile OpenAPI]
+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.

modules/reference/pages/feature/mpOpenAPI-3.1/examples.adoc

@@ -1,9 +1,9 @@
 
 === Configure OpenAPI documentation for a multi-module application
 
-// This example only applies to 2.0 forward, and so the file and directory must be manually copied and applied to any new versions. Copy the directory and file and change the directory name to reflect the new feature version, for example `mpOpenAPI-3.2`.
+// This example applies only to versions 2.0-3.1.
 
-By default, only the first module of the first deployed application is included in the OpenAPI documentation. However, you can configure the MicroProfile OpenAPI feature to merge the OpenAPI documentation for multiple applications or modules into a single document.
+Only the first module of the first deployed application is included in the OpenAPI documentation by default. However, you can configure the MicroProfile OpenAPI feature to merge the 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 containing five web modules.
 
@@ -26,13 +26,13 @@ For example, the following configuration is for the `sample_app` application, wh
 </mpOpenAPI>
 ----
 
-- The `<includeApplication>` element specifies that all applications are included in the final OpenAPI document.
+- 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 `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.
+- The `info` element sets the info section for the final OpenAPI document, which documents web modules 1, 2, and 4.
 
-=== Naming applications and modules   
+==== 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:
 +
@@ -45,9 +45,11 @@ If the application is deployed in the `dropins` directory or if the `name` attri
 +
 - The module name is specified in the web module's `web.xml` file. If there is no `web.xml` file or if it does not specify a name, the module name defaults to the filename with the extension removed.
 
+For more information, see xref:ROOT:documentation-openapi.adoc#multi-module[Multiple application and multi-module application support with MicroProfile OpenAPI]
+
 === Override the info section in the OpenAPI document
 
-You can also override the `info` section of the OpenAPI document using the following configuration:
+You can override the `info` section of the OpenAPI document specifying the `info` element within the `mpOpenAPI` element:
 
 [source,xml]
 ----
@@ -58,8 +60,4 @@ You can also override the `info` section of the OpenAPI document using the follo
 </mpOpenAPI>
 ----
 
-Overriding the `info` section is useful for documenting multiple modules or applications. Without an override, the `info` section can be replaced with a standard version which indicates that documentation from several modules was merged.
-
-For more information, see xref:ROOT:documentation-openapi.adoc#multi-module[Multiple application and multi-module application support with MicroProfile OpenAPI]
-
-
+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.

modules/reference/pages/feature/mpOpenAPI-4.0/examples.adoc

@@ -1,10 +1,10 @@
 
-
+[#mm]
 === Configure OpenAPI documentation for a multi-module application
 
-// This example only applies to 2.0 forward, and so the file and directory must be manually copied and applied to any new versions. Copy the directory and file and change the directory name to reflect the new feature version, for example `mpOpenAPI-3.2`.
+// This example only applies to 4.0 forward, and so the file and directory must be manually copied and applied to any new versions. Copy the directory and file and change the directory name to reflect the new feature version, for example `mpOpenAPI-4.1`.
 
-By default, all deployed applications and modules are included in the OpenAPI documentation. However, you can configure which applications and modules should be included.
+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.
 
@@ -26,11 +26,11 @@ For example, the following configuration is for the `sample_app` application, wh
 </mpOpenAPI>
 ----
 
-- The `<excludeModule>` elements exclude the `module-3` and `module-5` web modules.
+- 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.
+- The `info` element sets the info section for the final OpenAPI document, which documents web modules 1, 2, and 4.
 
-=== Naming applications and modules   
+==== 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:
 +
@@ -39,13 +39,16 @@ For example, the following configuration is for the `sample_app` application, wh
 <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 with the extension removed.
+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 there is no `web.xml` file or if it does not specify a name, the module name defaults to the filename with the extension removed.
+- 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 xref:ROOT:documentation-openapi.adoc#multi-module[Multiple application and multi-module application support with MicroProfile OpenAPI].
+
 
 === Override the info section in the OpenAPI document
 
-You can also override the `info` section of the OpenAPI document using the following configuration:
+You can override the `info` section of the OpenAPI document specifying the `info` element within the `mpOpenAPI` element:
 
 [source,xml]
 ----
@@ -56,17 +59,15 @@ You can also override the `info` section of the OpenAPI document using the follo
 </mpOpenAPI>
 ----
 
-Overriding the `info` section is useful for documenting multiple modules or applications. Without an override, the `info` section can be replaced with a standard version which indicates that documentation from several modules was merged.
+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.
 
 [#apiversion]
 === 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 end users use tools or libraries that don't yet support a newer version of the OpenAPI specification.
+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, you can select OpenAPI v3.0 when using `mpOpenAPI-4.0`.
+For example, `mpOpenAPI-4.0` defaults to OpenAPI 3.1, but you can specify the following configuration to set it to OpenAPI 3.0.
 
 [source,xml]
 ----
 <mpOpenAPI openAPIVersion="3.0"/>
 ----
-
-For more information, see xref:ROOT:documentation-openapi.adoc#multi-module[Multiple application and multi-module application support with MicroProfile OpenAPI]