[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

@@ -91,6 +91,7 @@ These options may be applied as additional-properties (cli) or configOptions (pl
 |x-discriminator-value|Used with model inheritance to specify value for discriminator that identifies current model|MODEL|
 |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-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

@@ -145,6 +145,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

@@ -265,9 +265,26 @@ 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."
+                    + " Values are strings, applied at render time, and overwrite existing values."
+                    + " For the extra-annotation extensions, separate multiple annotations in a single"
+                    + " value with spaces (e.g. ModelName.x-class-extra-annotation=@Foo @Bar), not"
+                    + " commas, since an unquoted comma separates different injection targets."
                     + " You can also have multiple occurrences of this option.")
     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."
+                    + " For the extra-annotation extensions, separate multiple annotations in a single"
+                    + " value with spaces (e.g. operationId.x-operation-extra-annotation=@Foo @Bar), not"
+                    + " commas, since an unquoted comma separates different injection targets."
+                    + " You can also have multiple occurrences of this option.")
+    private List<String> injectOperationVendorExtensions = new ArrayList<>();
+
     @Option(
             name = {"--openapi-normalizer"},
             title = "OpenAPI normalizer rules",
@@ -616,6 +633,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);

modules/openapi-generator-core/src/main/java/org/openapitools/codegen/config/GeneratorSettings.java

@@ -60,6 +60,7 @@ public final class GeneratorSettings implements Serializable {
     private final Map<String, String> enumNameMappings;
     private final Map<String, String> operationIdNameMappings;
     private final Map<String, String> injectModelVendorExtensions;
+    private final Map<String, String> injectOperationVendorExtensions;
     private final Map<String, String> openapiNormalizer;
     private final Set<String> languageSpecificPrimitives;
     private final Set<String> openapiGeneratorIgnoreList;
@@ -337,6 +338,15 @@ public Map<String, String> getInjectModelVendorExtensions() {
         return injectModelVendorExtensions;
     }
 
+    /**
+     * Gets inject operation vendor extensions.
+     *
+     * @return a map of operationId.x-extension-name or operationId.paramBaseName.x-extension-name to extension value
+     */
+    public Map<String, String> getInjectOperationVendorExtensions() {
+        return injectOperationVendorExtensions;
+    }
+
     /**
      * Gets OpenAPI normalizer rules
      *
@@ -480,6 +490,7 @@ private GeneratorSettings(Builder builder) {
         enumNameMappings = Collections.unmodifiableMap(builder.enumNameMappings);
         operationIdNameMappings = Collections.unmodifiableMap(builder.operationIdNameMappings);
         injectModelVendorExtensions = Collections.unmodifiableMap(builder.injectModelVendorExtensions);
+        injectOperationVendorExtensions = Collections.unmodifiableMap(builder.injectOperationVendorExtensions);
         openapiNormalizer = Collections.unmodifiableMap(builder.openapiNormalizer);
         languageSpecificPrimitives = Collections.unmodifiableSet(builder.languageSpecificPrimitives);
         openapiGeneratorIgnoreList = Collections.unmodifiableSet(builder.openapiGeneratorIgnoreList);
@@ -562,6 +573,7 @@ public GeneratorSettings() {
         enumNameMappings = Collections.unmodifiableMap(new HashMap<>(0));
         operationIdNameMappings = Collections.unmodifiableMap(new HashMap<>(0));
         injectModelVendorExtensions = Collections.unmodifiableMap(new HashMap<>(0));
+        injectOperationVendorExtensions = Collections.unmodifiableMap(new HashMap<>(0));
         openapiNormalizer = Collections.unmodifiableMap(new HashMap<>(0));
         languageSpecificPrimitives = Collections.unmodifiableSet(new HashSet<>(0));
         openapiGeneratorIgnoreList = Collections.unmodifiableSet(new HashSet<>(0));
@@ -645,6 +657,9 @@ public static Builder newBuilder(GeneratorSettings copy) {
         if (copy.getInjectModelVendorExtensions() != null) {
             builder.injectModelVendorExtensions.putAll(copy.getInjectModelVendorExtensions());
         }
+        if (copy.getInjectOperationVendorExtensions() != null) {
+            builder.injectOperationVendorExtensions.putAll(copy.getInjectOperationVendorExtensions());
+        }
         if (copy.getOpenapiNormalizer() != null) {
             builder.openapiNormalizer.putAll(copy.getOpenapiNormalizer());
         }
@@ -700,6 +715,7 @@ public static final class Builder {
         private Map<String, String> enumNameMappings;
         private Map<String, String> operationIdNameMappings;
         private Map<String, String> injectModelVendorExtensions;
+        private Map<String, String> injectOperationVendorExtensions;
         private Map<String, String> openapiNormalizer;
         private Set<String> languageSpecificPrimitives;
         private Set<String> openapiGeneratorIgnoreList;
@@ -729,6 +745,7 @@ public Builder() {
             enumNameMappings = new HashMap<>();
             operationIdNameMappings = new HashMap<>();
             injectModelVendorExtensions = new HashMap<>();
+            injectOperationVendorExtensions = new HashMap<>();
             openapiNormalizer = new HashMap<>();
             languageSpecificPrimitives = new HashSet<>();
             openapiGeneratorIgnoreList = new HashSet<>();
@@ -1236,6 +1253,32 @@ public Builder withInjectModelVendorExtension(String key, String value) {
             return this;
         }
 
+        /**
+         * Sets the {@code injectOperationVendorExtensions} and returns a reference to this Builder so that the methods can be chained together.
+         *
+         * @param injectOperationVendorExtensions the {@code injectOperationVendorExtensions} to set
+         * @return a reference to this Builder
+         */
+        public Builder withInjectOperationVendorExtensions(Map<String, String> injectOperationVendorExtensions) {
+            this.injectOperationVendorExtensions = injectOperationVendorExtensions;
+            return this;
+        }
+
+        /**
+         * Sets a single {@code injectOperationVendorExtension} and returns a reference to this Builder so that the methods can be chained together.
+         *
+         * @param key   A key in the format operationId.x-extension-name or operationId.paramBaseName.x-extension-name
+         * @param value The extension value
+         * @return a reference to this Builder
+         */
+        public Builder withInjectOperationVendorExtension(String key, String value) {
+            if (this.injectOperationVendorExtensions == null) {
+                this.injectOperationVendorExtensions = new HashMap<>();
+            }
+            this.injectOperationVendorExtensions.put(key, value);
+            return this;
+        }
+
         /**
          * Sets the {@code openapiNormalizer} and returns a reference to this Builder so that the methods can be chained together.
          *
@@ -1482,6 +1525,8 @@ public boolean equals(Object o) {
                 Objects.equals(getModelNameMappings(), that.getModelNameMappings()) &&
                 Objects.equals(getEnumNameMappings(), that.getEnumNameMappings()) &&
                 Objects.equals(getOperationIdNameMappings(), that.getOperationIdNameMappings()) &&
+                Objects.equals(getInjectModelVendorExtensions(), that.getInjectModelVendorExtensions()) &&
+                Objects.equals(getInjectOperationVendorExtensions(), that.getInjectOperationVendorExtensions()) &&
                 Objects.equals(getOpenapiNormalizer(), that.getOpenapiNormalizer()) &&
                 Objects.equals(getLanguageSpecificPrimitives(), that.getLanguageSpecificPrimitives()) &&
                 Objects.equals(getOpenapiGeneratorIgnoreList(), that.getOpenapiGeneratorIgnoreList()) &&
@@ -1521,6 +1566,8 @@ public int hashCode() {
                 getModelNameMappings(),
                 getEnumNameMappings(),
                 getOperationIdNameMappings(),
+                getInjectModelVendorExtensions(),
+                getInjectOperationVendorExtensions(),
                 getOpenapiNormalizer(),
                 getLanguageSpecificPrimitives(),
                 getOpenapiGeneratorIgnoreList(),

modules/openapi-generator-gradle-plugin/README.adoc

@@ -200,6 +200,16 @@ apply plugin: 'org.openapi.generator'
 |None
 |Sets specified global properties.
 
+|injectModelVendorExtensions
+|Map / Provider<Map>
+|None
+|Injects vendor extensions into models or their properties without editing the input spec. Keys use the form `modelName.x-extension-name` (model) or `modelName.propertyBaseName.x-extension-name` (model property). See the note below on supplying multiple annotations in a single value.
+
+|injectOperationVendorExtensions
+|Map / Provider<Map>
+|None
+|Injects vendor extensions into operations or their parameters without editing the input spec. Keys use the form `operationId.x-extension-name` (operation) or `operationId.paramBaseName.x-extension-name` (parameter, matched by its raw spec name). See the note below on supplying multiple annotations in a single value.
+
 |configFile
 |String / Provider<RegularFile>
 |None
@@ -564,6 +574,21 @@ models: "User:Pet"
 ----
 ====
 
+[NOTE]
+====
+`injectModelVendorExtensions` and `injectOperationVendorExtensions` are a generic mechanism for
+setting *any* vendor extension on a model, property, operation, or parameter without editing the spec.
+Keep in mind:
+
+* Values are always strings, applied *late* (at codegen/render time) and **overwrite** any existing
+  value; missing targets are a silent no-op. It is best suited to extensions consumed by templates,
+  such as the Spring extra-annotation extensions.
+* For the extra-annotation extensions, put multiple annotations in one value separated by *spaces*
+  (as in source), e.g. `"addPet.x-request-body-extra-annotation": "@com.example.MyValidation @Valid"`.
+  In the Gradle map form commas inside a value need no escaping, so `@Size(min = 0, max = 10)` works
+  directly (unlike the comma-separated CLI/Maven form).
+====
+
 === openApiValidate
 
 .Options

modules/openapi-generator-gradle-plugin/src/main/kotlin/org/openapitools/generator/gradle/plugin/OpenApiGeneratorPlugin.kt

@@ -127,6 +127,8 @@ class OpenApiGeneratorPlugin : Plugin<Project> {
                     templateResourcePath.set(generate.templateResourcePath)
                     auth.set(generate.auth)
                     globalProperties.set(generate.globalProperties)
+                    injectModelVendorExtensions.set(generate.injectModelVendorExtensions)
+                    injectOperationVendorExtensions.set(generate.injectOperationVendorExtensions)
                     configFile.set(generate.configFile)
                     skipOverwrite.set(generate.skipOverwrite)
                     packageName.set(generate.packageName)

modules/openapi-generator-gradle-plugin/src/main/kotlin/org/openapitools/generator/gradle/plugin/extensions/OpenApiGeneratorGenerateExtension.kt

@@ -163,6 +163,24 @@ open class OpenApiGeneratorGenerateExtension(private val project: Project) {
      */
     val globalProperties = project.objects.mapProperty<String, String>()
 
+    /**
+     * Injects vendor extensions into models or their properties without editing the input spec.
+     *
+     * Keys use the form {@code modelName.x-extension-name} for a model or
+     * {@code modelName.propertyBaseName.x-extension-name} for a model property; the value is the
+     * extension value.
+     */
+    val injectModelVendorExtensions = project.objects.mapProperty<String, String>()
+
+    /**
+     * Injects vendor extensions into operations or their parameters without editing the input spec.
+     *
+     * Keys use the form {@code operationId.x-extension-name} for an operation or
+     * {@code operationId.paramBaseName.x-extension-name} for a parameter (matched by its raw spec
+     * name); the value is the extension value.
+     */
+    val injectOperationVendorExtensions = project.objects.mapProperty<String, String>()
+
     /**
      * Path to json configuration file.
      * File content should be in a json format { "optionKey":"optionValue", "optionKey1":"optionValue1"...}