[JAVA-SPRING;KOTLIN-SPRING] feature: x-field-extra-annotation parity for kotlin-spring params + new x-request-body-extra-annotation + --inject-operation-vendor-extensions

bin/configs/kotlin-spring-boot-delegate.yaml

@@ -1,8 +1,13 @@
 generatorName: kotlin-spring
 outputDir: samples/server/petstore/kotlin-springboot-delegate
 library: spring-boot
-inputSpec: modules/openapi-generator/src/test/resources/3_0/petstore.yaml
+inputSpec: modules/openapi-generator/src/test/resources/3_0/kotlin/petstore-with-extra-annotation.yaml
 templateDir: modules/openapi-generator/src/main/resources/kotlin-spring
+injectOperationVendorExtensions:
+  placeOrder.x-request-body-extra-annotation: "@NonNull"
+  placeOrder.x-extra-imports: org.springframework.lang.NonNull
+  getOrderById.orderId.x-field-extra-annotation: "@NonNull"
+  getOrderById.orderId.x-extra-imports: org.springframework.lang.NonNull
 additionalProperties:
   generateJsonIncludeAnnotations: "true"
   generateJsonSetterNullsAnnotations: "true"

bin/configs/kotlin-spring-boot-reactive.yaml

@@ -1,8 +1,13 @@
 generatorName: kotlin-spring
 outputDir: samples/server/petstore/kotlin-springboot-reactive
 library: spring-boot
-inputSpec: modules/openapi-generator/src/test/resources/3_0/petstore.yaml
+inputSpec: modules/openapi-generator/src/test/resources/3_0/kotlin/petstore-with-extra-annotation.yaml
 templateDir: modules/openapi-generator/src/main/resources/kotlin-spring
+injectOperationVendorExtensions:
+  placeOrder.x-request-body-extra-annotation: "@NonNull"
+  placeOrder.x-extra-imports: org.springframework.lang.NonNull
+  getOrderById.orderId.x-field-extra-annotation: "@NonNull"
+  getOrderById.orderId.x-extra-imports: org.springframework.lang.NonNull
 additionalProperties:
   generateJsonIncludeAnnotations: "true"
   generateJsonSetterNullsAnnotations: "true"

bin/configs/spring-boot-reactive.yaml

@@ -1,7 +1,10 @@
 generatorName: spring
 outputDir: samples/server/petstore/springboot-reactive
-inputSpec: modules/openapi-generator/src/test/resources/3_0/spring/petstore-with-fake-endpoints-models-for-testing.yaml
+inputSpec: modules/openapi-generator/src/test/resources/3_0/spring/petstore-with-fake-endpoints-models-for-testing-extra-annotation.yaml
 templateDir: modules/openapi-generator/src/main/resources/JavaSpring
+injectOperationVendorExtensions:
+  placeOrder.x-request-body-extra-annotation: "@org.springframework.lang.NonNull"
+  getOrderById.order_id.x-field-extra-annotation: "@org.springframework.lang.NonNull"
 additionalProperties:
   generateJsonIncludeAnnotations: "true"
   generateJsonSetterNullsAnnotations: "true"

bin/configs/spring-boot-useoptional.yaml

@@ -1,7 +1,10 @@
 generatorName: spring
 outputDir: samples/server/petstore/springboot-useoptional
-inputSpec: modules/openapi-generator/src/test/resources/3_0/spring/petstore-with-fake-endpoints-models-for-testing.yaml
+inputSpec: modules/openapi-generator/src/test/resources/3_0/spring/petstore-with-fake-endpoints-models-for-testing-extra-annotation.yaml
 templateDir: modules/openapi-generator/src/main/resources/JavaSpring
+injectOperationVendorExtensions:
+  placeOrder.x-request-body-extra-annotation: "@org.springframework.lang.NonNull"
+  getOrderById.order_id.x-field-extra-annotation: "@org.springframework.lang.NonNull"
 additionalProperties:
   generateJsonIncludeAnnotations: "true"
   generateJsonSetterNullsAnnotations: "true"

docs/generators/kotlin-spring.md

@@ -93,6 +93,7 @@ These options may be applied as additional-properties (cli) or configOptions (pl
 |x-field-extra-annotation|Custom annotation(s) to be added to property; accepts a string or list of strings|FIELD, OPERATION_PARAMETER|null
 |x-jackson-default-impl|Specifies the default implementation class name for Jackson @JsonTypeInfo(defaultImpl=...) on a oneOf interface schema (deduction-based or discriminator-based). Can be overridden per-schema by the `typeInfoDefaultImpls` generator option.|MODEL|null
 |x-operation-extra-annotation|Custom annotation(s) to be added to operation; accepts a string or list of strings|OPERATION|null
+|x-request-body-extra-annotation|Custom annotation(s) to be added to the request body parameter; accepts a string or list of strings. Declared on the operation because the request body typically `$ref`s a shared model (so the annotation cannot be placed next to the `$ref`); the value is rendered by being merged into the body parameter's `x-field-extra-annotation`|OPERATION|null
 |x-extra-imports|Custom import(s) to add to the generated file that declares the annotated model, property, operation, or parameter (e.g. so custom annotations can be referenced by their short name); accepts a string or list of strings. Values are emitted verbatim (Kotlin alias imports supported) and only exact duplicates are removed|MODEL, FIELD, OPERATION, OPERATION_PARAMETER|null
 |x-pattern-message|Add this property whenever you need to customize the invalidation error message for the regex pattern of a variable|FIELD, OPERATION_PARAMETER|null
 |x-size-message|Add this property whenever you need to customize the invalidation error message for the size or length of a variable|FIELD, OPERATION_PARAMETER|null

docs/generators/spring.md

@@ -146,6 +146,7 @@ These options may be applied as additional-properties (cli) or configOptions (pl
 |x-class-extra-annotation|Custom annotation(s) to be added to model; accepts a string or list of strings|MODEL|null
 |x-field-extra-annotation|Custom annotation(s) to be added to property; accepts a string or list of strings|FIELD, OPERATION_PARAMETER|null
 |x-operation-extra-annotation|Custom annotation(s) to be added to operation; accepts a string or list of strings|OPERATION|null
+|x-request-body-extra-annotation|Custom annotation(s) to be added to the request body parameter; accepts a string or list of strings. Declared on the operation because the request body typically `$ref`s a shared model (so the annotation cannot be placed next to the `$ref`); the value is rendered by being merged into the body parameter's `x-field-extra-annotation`|OPERATION|null
 |x-spring-paginated|Add `org.springframework.data.domain.Pageable` to controller method. Can be used to handle `page`, `size` and `sort` query parameters. If these query parameters are also specified in the operation spec, they will be removed from the controller method as their values can be obtained from the `Pageable` object. Applies when `library=spring-boot` or `library=spring-cloud`; ignored for other (client) libraries.|OPERATION|false
 |x-version-param|Marker property that tells that this parameter would be used for endpoint versioning. Applicable for headers & query params. true/false|OPERATION_PARAMETER|null
 |x-pattern-message|Add this property whenever you need to customize the invalidation error message for the regex pattern of a variable|FIELD, OPERATION_PARAMETER|null

modules/openapi-generator-cli/src/main/java/org/openapitools/codegen/cmd/Generate.java

@@ -256,9 +256,50 @@ public class Generate extends OpenApiGeneratorCommand {
             description = "injects vendor extensions into model classes or their properties."
                     + " Class-level format: ModelName.x-extension-name=value."
                     + " Property-level format: ModelName.propertyBaseName.x-extension-name=value."
-                    + " You can also have multiple occurrences of this option.")
+                    + " Values are strings, applied at render time, and overwrite existing values."
+                    + " Each occurrence of this option is exactly one key=value pair; everything after"
+                    + " the first '=' (including any commas, e.g. for @Size(min = 1, max = 100)) is"
+                    + " taken literally as the value, so annotation arguments do not need escaping."
+                    + " For the extra-annotation extensions, separate multiple annotations rendered on"
+                    + " the same line within a single value with spaces (e.g."
+                    + " 'ModelName.x-class-extra-annotation=@JsonProperty(value = \"example\") @Deprecated'),"
+                    + " or repeat this option with the same key to add another list entry (e.g. run it once"
+                    + " with 'ModelName.x-class-extra-annotation=@Foo' and again with"
+                    + " 'ModelName.x-class-extra-annotation=@Bar'); templates that loop over the extension"
+                    + " (such as class- and property-level extra-annotations) render each repeated"
+                    + " occurrence on its own line, in the order given."
+                    + " Quote the whole key=value pair when the value contains spaces (e.g."
+                    + " \"ModelName.x-class-extra-annotation=@Foo(\\\"some string with spaces\\\")\"),"
+                    + " and if your shell requires double-quoting the whole argument instead, escape"
+                    + " embedded double quotes (e.g. \\\")."
+                    + " You can have multiple occurrences of this option, one per injection target.")
     private List<String> injectModelVendorExtensions = new ArrayList<>();
 
+    @Option(
+            name = {"--inject-operation-vendor-extensions"},
+            title = "inject operation vendor extensions",
+            description = "injects vendor extensions into operations or their parameters."
+                    + " Operation-level format: operationId.x-extension-name=value."
+                    + " Parameter-level format: operationId.paramBaseName.x-extension-name=value."
+                    + " Values are strings, applied at render time, and overwrite existing values."
+                    + " Each occurrence of this option is exactly one key=value pair; everything after"
+                    + " the first '=' (including any commas, e.g. for @Size(min = 1, max = 100)) is"
+                    + " taken literally as the value, so annotation arguments do not need escaping."
+                    + " For the extra-annotation extensions, separate multiple annotations rendered on"
+                    + " the same line within a single value with spaces (e.g."
+                    + " 'operationId.x-operation-extra-annotation=@JsonProperty(value = \"example\") @Deprecated'),"
+                    + " or repeat this option with the same key to add another list entry (e.g. run it once"
+                    + " with 'operationId.x-operation-extra-annotation=@Foo' and again with"
+                    + " 'operationId.x-operation-extra-annotation=@Bar'); templates that loop over the"
+                    + " extension (such as operation-level extra-annotations) render each repeated"
+                    + " occurrence on its own line, in the order given."
+                    + " Quote the whole key=value pair when the value contains spaces (e.g."
+                    + " \"operationId.x-operation-extra-annotation=@Foo(\\\"some string with spaces\\\")\"),"
+                    + " and if your shell requires double-quoting the whole argument instead, escape"
+                    + " embedded double quotes (e.g. \\\")."
+                    + " You can have multiple occurrences of this option, one per injection target.")
+    private List<String> injectOperationVendorExtensions = new ArrayList<>();
+
     @Option(
             name = {"--openapi-normalizer"},
             title = "OpenAPI normalizer rules",
@@ -606,6 +647,7 @@ public void execute() {
         applyEnumNameMappingsKvpList(enumNameMappings, configurator);
         applyOperationIdNameMappingsKvpList(operationIdNameMappings, configurator);
         applyInjectModelVendorExtensionsKvpList(injectModelVendorExtensions, configurator);
+        applyInjectOperationVendorExtensionsKvpList(injectOperationVendorExtensions, configurator);
         applyOpenapiNormalizerKvpList(openapiNormalizer, configurator);
         applyTypeMappingsKvpList(typeMappings, configurator);
         applyAdditionalPropertiesKvpList(additionalProperties, configurator);