Correct errors in how OpenAPI generator config settings are set

Signed-off-by: Tim Quinn <[email protected]>
helidon-io · Nov 7, 2023 · 6129eed · 6129eed
1 parent 0a43710
commit 6129eed
Showing 1 changed file with 44 additions and 11 deletions.
diff --git a/docs/shared/openapi/openapi-generator.adoc b/docs/shared/openapi/openapi-generator.adoc
@@ -1,6 +1,6 @@
 ///////////////////////////////////////////////////////////////////////////////
 
-    Copyright (c) 2022 Oracle and/or its affiliates.
+    Copyright (c) 2022, 2023 Oracle and/or its affiliates.
 
     Licensed under the Apache License, Version 2.0 (the "License");
     you may not use this file except in compliance with the License.
@@ -139,11 +139,11 @@ For complete lists see these pages:
 * link:{openapi-generator-tool-generators-docs-url}/java-helidon-client.md[Helidon client generator options] and
 * link:{openapi-generator-tool-generators-docs-url}/java-helidon-server.md[Helidon server generator options]
 
-The OpenAPI generator divides its settings into two types:
+The OpenAPI generator loosely divides its settings into three types:
 
-* _options_
+* _global properties_
 +
-These high-level settings generally govern the overall behavior of the tool.
+These settings generally govern the overall behavior of the tool, regardless of which specific generator you use.
 +
 For the CLI, use the common option style:
 +
@@ -159,9 +159,38 @@ For the Maven plug-in, use elements within the `<configuration>` section of the
     <inputSpec>petstore.yaml</inputSpec>
 </configuration>
 ----
+* _options_
++
+These settings typically affect how particular generators operate.
++
+For the CLI, specify config options as additional properties:
++
+`--additional-properties=groupId=com.mycompany.test,artifactId=my-example`
++
+or
++
+[source,bash]
+----
+-p groupId=com.mycompany.test
+-p artifactId=my-example
+----
++
+For the Maven plug-in, use the `<configOptions>` section within `<configuration>`:
++
+[source,xml]
+----
+<configuration>
+    ...
+    <configOptions>
+        <groupId>com.mycompany.test</groupId>
+        <artifactId>my-example</artifactId>
+    </configOptions>
+    ...
+</configuration>
+----
 * _additional properties_
 +
-These settings typically affect how a specific generator or library generates the code.
+Settings in this category typically are passed to the templates used in generating the files, although generators can use additional properties in deciding how to generate the files.
 +
 For the CLI:
 +
@@ -175,16 +204,17 @@ or
 -p returnResponse=true
 ----
 +
-For the Maven plug-in, use elements within the `<configuration><configOptions>` section:
+For the Maven plug-in, use an `<additionalProperties>` section within the `<configuration>` section for the plug-in:
 +
 [source,xml]
 ----
 <configuration>
-    ....
-    <configOptions>
-        <useAbstractClasses>false</useAbstractClasses>
-        <returnResponse>true</returnResponse>
-    </configOptions>
+    ...
+    <additionalProperties>
+        <additionalProperty>useAbstractClasses=false</additionalProperty>
+        <additionalProperty>returnResponse=true</additionalProperty>
+    </additionalProperties>
+    ...
 </configuration>
 ----
 
@@ -490,6 +520,9 @@ The plug-in execution in the following example is equivalent to the CLI example
                     <modelPackage>io.helidon.examples.openapigen.{flavor-lc}.{example-project-type}.model</modelPackage>
                     <invokerPackage>io.helidon.examples.openapigen.{flavor-lc}.{example-project-type}</invokerPackage>
                 </configOptions>
+                <additionalProperties>
+                    <additionalProperty>returnResponse=true</additionalProperty>
+                </additionalProperties>
             </configuration>
         </execution>
     </executions>