From 163b83758bd4a01975a48ef8ef1209298038bfc2 Mon Sep 17 00:00:00 2001 From: Ramkumar K Date: Wed, 27 Nov 2024 16:28:28 +0530 Subject: [PATCH] 7654-Documentation-MicroProfile-OpenAPI-4.0-012 7654-Documentation-MicroProfile-OpenAPI-4.0-012 #7654 --- modules/ROOT/pages/documentation-openapi.adoc | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/modules/ROOT/pages/documentation-openapi.adoc b/modules/ROOT/pages/documentation-openapi.adoc index 8d2ea5503..cd85a3dc9 100644 --- a/modules/ROOT/pages/documentation-openapi.adoc +++ b/modules/ROOT/pages/documentation-openapi.adoc @@ -182,11 +182,11 @@ When multiple applications or an application with more than one web module are d [#conf-mm-supprt] === Including and excluding applications and modules from OpenAPI documentation -You can configure which applications or modules are included in your OpenAPI documentation either by <> or by <>. For most scenarios, `server.xml` configuration is preferred and MicroProfile Config properties are recommended only for compatibility with existing configurations that are already using these properties. +You can configure which applications or modules are included in your OpenAPI documentation either by <<#server, setting elements in your `server.xml` file>> or by <<#mp-config, specifying MicroProfile Config properties>>. For most scenarios, `server.xml` configuration is preferred and MicroProfile Config properties are recommended only for compatibility with existing configurations that are already using these properties. [#server] ==== 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 following elements within the config:mpOpenAPI[] configuration element in your `server.xml` file: +You can control the inclusion and exclusion of applications and modules in the OpenAPI documentation by configuring the following elements within the config:mpOpenAPI[] configuration element in your `server.xml` file: - `excludeModule` | `excludeApplication`: Specify module or application names, one per element, that are to be excluded from the OpenAPI document. Specify module names in the `{ApplicationName}/{ModuleName}` format. - `includeModule` | `includeApplication`: Specify module or application names, one per element, that are to be included in the OpenAPI document. Specify module names in the `{ApplicationName}/{ModuleName}` format. The `all` special value includes all available applications. @@ -194,7 +194,7 @@ You can control the inclusion and exclusion of applications and modules in the O In feature:mpOpenAPI-4.0[display=MicroProfile OpenAPI 4.0] and later, all applications and modules are included by default. To exclude certain applications or modules, specify the `excludeModule` or `excludeApplication` element within the `mpOpenAPI` element. -In the following example, the `sample_app` application consists of an EAR file containing five web modules. This configuration excludes modules 3 and 5 and provides a custom `info` section for the merged API documentation for modules 1,2, and 4: +In the following example, the `sample_app` application consists of an EAR file containing five web modules. This configuration excludes modules 3 and 5 and provides a custom `info` section for the merged API documentation for modules 1, 2, and 4: [source,xml] ---- @@ -216,7 +216,7 @@ In the following example, the `sample_app` application consists of an EAR file c In MicroProfile MicroProfile OpenAPI 2.0 - feature:mpOpenAPI-3.1[display=3.1], only the first web module of the first deployed application is included in the structured documentation. To include or exclude applications specify the corresponding elements within the `mpOpenAPI` element. -In the following example, the `sample_app` application consists of an EAR file containing five web modules. By default, only `module-1` is included in the documentation. This configuration includes all modules, then selectively excludes modules 3 and 5. It also provides a custom `info` section for the merged API documentation for modules 1,2, and 4: +In the following example, the `sample_app` application consists of an EAR file containing five web modules. By default, only `module-1` is included in the documentation. This configuration includes all modules, then selectively excludes modules 3 and 5. It also provides a custom `info` section for the merged API documentation for modules 1, 2, and 4: [source,xml] ---- @@ -253,7 +253,7 @@ For module names, the module name is specified in the web module's `web.xml` fil 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. -WHen you configure the inclusion or exclusion of modules or applications with MicroProfile Config, the following limitations apply: +When you configure the inclusion or exclusion of modules or applications with MicroProfile Config, the following limitations apply: - You must configure properties in a source that applies to the entire runtime, such as the `bootstrap.properties`, `jvm.properties`, or `server.env` files, or the `variable` element in the `server.xml` file. - 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. @@ -292,7 +292,7 @@ This value excludes no applications or web modules. |=== -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. +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. In the following `jvm.properties` file example, an OpenAPI document is configured for the `sample_app` application, which consists of an EAR file with five web modules.