7654-Documentation-MicroProfile-OpenAPI-4.0-9

7654-Documentation-MicroProfile-OpenAPI-4.0-9

#7654

modules/ROOT/pages/documentation-openapi.adoc

@@ -18,11 +18,11 @@ Other developers need relevant information to build an application that communic
 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 following sections provide more information about the available approaches, supported versions, and configurations for using MicroProfile OpenAPI with Open Liberty.
-- <<#code1, The code-first approach>>
-- <<#design1, The design-first approach>>
-- <<#supp-ver, Supported OpenAPI versions>>
-- <<#multi-module, Multiple application and multi-module application support with MicroProfile OpenAPI>>
-- <<#conf-mm-supprt, Configuring multiple application and multi-module support>>
+
+* <<#code1, The code-first approach>>
+* <<#design1, The design-first approach>>
+* <<#supp-ver, Supported OpenAPI versions>>
+* <<#multi-module, Multiple application and multi-module application support>>
 
 
 You can implement MicroProfile OpenAPI for Open Liberty by enabling the feature:mpOpenAPI[display=MicroProfile OpenAPI] feature. When this feature is enabled, you can view the OpenAPI document in a browser by using the `/openapi` endpoint. For example, if your browser is on the same machine where your server is running, you can view the raw OpenAPI document at the `\http://localhost:9080/openapi` URL or view the OpenAPI document in a user interface at the `\http://localhost:9080/openapi/ui` URL.
@@ -157,12 +157,8 @@ 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 example, you can select OpenAPI v3.0 when using `mpOpenAPI-4.0`.
+For more information, see link:/docs/latest/reference/feature/mpOpenAPI-4.0.html#apiversion[Selecting the OpenAPI specification version].
 
-[source,xml]
-----
-<mpOpenAPI openAPIVersion="3.0"/>
-----
 
 [#multi-module]
 == Multiple application and multi-module application support with MicroProfile OpenAPI
@@ -172,42 +168,52 @@ When multiple applications or applications with more than one web module are dep
 .Multiple application and multi-module application support with MicroProfile OpenAPI
 [cols="1,2", options="header"]
 |===
-|Feature |Behavior
+|Feature |Default behavior
 
 |`mpOpenAPI-4.0`
-|By default, 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, and the behavior can be modified through configuration.
 
 |`mpOpenAPI-2.0` to `mpOpenAPI-3.1`
-|By default, 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, but the behavior can be modified 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.
 |===
 
 [#conf-mm-supprt]
-== Configuring multiple application and multi-module support
+== Configuring multiple application and multi-module API documentation
 
 Open Liberty offers two main ways to configure support for multiple applications and multi-module projects.
 
-- Configure using the `server.xml` file
+=== 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:
+
+- `includeApplication`: Specifies applications to include in the documentation.
+- `excludeApplication`: Specifies applications to exclude from the documentation.
+- `includeModule`: Specifies modules to include in the documentation.
+- `excludeModule`: Specifies modules to exclude from the documentation.
 
-You can customize the structured API documentation that is generated for your applications by configuring the `server.xml` file. By using the `includeApplication`, `excludeApplication`, `includeModule`, and `excludeModule` elements within the `mpOpenAPI` configuration, you gain precise control over which applications and modules are included in the OpenAPI documentation. This flexibility is useful for tailoring the documentation to your specific needs, such as excluding sensitive modules or overriding default metadata. The following sections provide examples and explain how to configure these elements effectively.
+This configuration provides flexibility to tailor the documentation to your specific needs, such as excluding sensitive modules or overriding default metadata.
 
-for more information, see the feature:mpOpenAPI[display=MicroProfile OpenAPI 4.0] feature.
+For more information, see the feature:mpOpenAPI[MicroProfile OpenAPI 4.0] feature.
 
-- Configure using MicroProfile Config properties
 
-MicroProfile Config provides a way to manage which applications and modules are included in the generated OpenAPI documentation by specifying configuration properties. With these properties, you can set inclusion and exclusion rules and customize the info section of the final OpenAPI document. This method is ideal for dynamic setups, enabling changes without directly modifying the `server.xml` file. However, there are some limitations. Configurations that are defined in the `server.xml` file take priority over those set through MicroProfile Config. Additionally, the properties must be set by using sources that apply to the entire server, such as `jvm.properties`, `server.env`, or environment variables.
+=== Configure by using MicroProfile Config properties
 
-for more information, see xref:reference:config/mpOpenAPI.adoc[MicroProfile Config properties for MicroProfile OpenAPI].
+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.
 
-=== Multi-module naming rules
+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.
 
-- When you configure support for multiple applications and multi-module environments by using MicroProfile Config, the application name is taken from the application's deployment descriptor (`application.xml` or `web.xml`). If there is no deployment descriptor or if it does not specify a name, the name defaults to the application archive filename with the extension removed.
-+
-- The module name follows the same rules as described for the `server.xml` configuration.
+- **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.
 
+For more information, see the xref:reference:config/mpOpenAPI.adoc[MicroProfile Config properties for MicroProfile OpenAPI].
 
 == See also
 

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

@@ -32,7 +32,7 @@ For example, the following configuration is for the `sample_app` application, wh
 
 - 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,7 +45,7 @@ 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.
 
-==== Override Info
+=== Override the info section in the OpenAPI document
 
 You can also override the `info` section of the OpenAPI document using the following configuration:
 

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

@@ -32,7 +32,7 @@ For example, the following configuration is for the `sample_app` application, wh
 
 - 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,7 +45,7 @@ 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.
 
-==== Override Info
+=== Override the info section in the OpenAPI document
 
 You can also override the `info` section of the OpenAPI document using the following configuration:
 

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

@@ -32,7 +32,7 @@ For example, the following configuration is for the `sample_app` application, wh
 
 - 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,7 +45,7 @@ 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.
 
-==== Override Info
+=== Override the info section in the OpenAPI document
 
 You can also override the `info` section of the OpenAPI document using the following configuration:
 

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

@@ -30,8 +30,7 @@ For example, the following configuration is for the `sample_app` application, wh
 
 - 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:
 +
@@ -44,7 +43,7 @@ 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.
 
-==== Override Info
+=== Override the info section in the OpenAPI document
 
 You can also override the `info` section of the OpenAPI document using the following configuration:
 
@@ -59,4 +58,15 @@ You can also override the `info` section of the OpenAPI document using the follo
 
 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.
 
+[#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.
+
+For example, you can select OpenAPI v3.0 when using `mpOpenAPI-4.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]