[kotlin-spring][server] Feat: Return from controllers without ResponseEntity wrapper. (#22377)

* remove "async" and "responseWrapper" from template as these are not supported by kotlin-spring generator

* try to force pipelines rerun

* force pipelines rerun

* fix mustache to keep generated code identical

* Revert "fix mustache to keep generated code identical"

This reverts commit c573b43.

* Reapply "fix mustache to keep generated code identical"

This reverts commit 2c3b065.

* Add support for 'useResponseEntity' in kotlin-spring. Consolidate with the separate flag 'declarativeInterfaceWrapResponses' as these can now be controlled both by one flag. Default to true.

* fix status annotation and add compile-test samples

* satisfy samples-up-to-date check

* add unit tests covering both reactive and non-reactive

* fix template to avoid unnecessary empty line

* fix template to avoid unnecessary empty line

* put method params (if present) on separate lines to improve readability

* put method params (if present) on separate lines to improve readability; fix double spaces, spaces before comma, incorrect spaces

* fix test

* store PATHs as accesible strings in companion objects.

* fix missing import

* fix incorrect import

* fix fallback to nested placeholders.

Author: Picazsoo

.github/workflows/samples-kotlin-server-jdk17.yaml

@@ -36,6 +36,7 @@ jobs:
           # server
           - samples/server/petstore/kotlin-server-required-and-nullable-properties
           - samples/server/petstore/kotlin-springboot-3
+          - samples/server/petstore/kotlin-springboot-3-no-response-entity
           - samples/server/petstore/kotlin-springboot-additionalproperties
           - samples/server/petstore/kotlin-springboot-delegate-nodefaults
           - samples/server/petstore/kotlin-springboot-request-cookie

.github/workflows/samples-kotlin-server.yaml

@@ -29,6 +29,8 @@ jobs:
         sample:
           # server
           - samples/server/petstore/kotlin-springboot
+          - samples/server/petstore/kotlin-springboot-no-response-entity
+          - samples/server/petstore/kotlin-springboot-no-response-entity-delegate
           - samples/server/petstore/kotlin-springboot-multipart-request-model
           - samples/server/petstore/kotlin-springboot-bigdecimal-default
           - samples/server/petstore/kotlin-springboot-delegate

bin/configs/kotlin-spring-boot-3-no-response-entity.yaml

@@ -0,0 +1,14 @@
+generatorName: kotlin-spring
+outputDir: samples/server/petstore/kotlin-springboot-3-no-response-entity
+library: spring-boot
+inputSpec: modules/openapi-generator/src/test/resources/3_0/petstore.yaml
+templateDir: modules/openapi-generator/src/main/resources/kotlin-spring
+additionalProperties:
+  documentationProvider: none
+  annotationLibrary: none
+  useSwaggerUI: "false"
+  serviceImplementation: "true"
+  serializableModel: "true"
+  beanValidations: "true"
+  useSpringBoot3: "true"
+  requestMappingMode: api_interface

bin/configs/kotlin-spring-boot-no-response-entity-delegate.yaml

@@ -0,0 +1,15 @@
+generatorName: kotlin-spring
+outputDir: samples/server/petstore/kotlin-springboot-no-response-entity-delegate
+library: spring-boot
+inputSpec: modules/openapi-generator/src/test/resources/2_0/petstore.yaml
+templateDir: modules/openapi-generator/src/main/resources/kotlin-spring
+additionalProperties:
+  documentationProvider: none
+  annotationLibrary: none
+  useSwaggerUI: "false"
+  serviceImplementation: "true"
+  serializableModel: "true"
+  beanValidations: "true"
+  useResponseEntity: "false"
+  delegatePattern: true
+  requestMappingMode: controller

bin/configs/kotlin-spring-boot-no-response-entity.yaml

@@ -0,0 +1,14 @@
+generatorName: kotlin-spring
+outputDir: samples/server/petstore/kotlin-springboot-no-response-entity
+library: spring-boot
+inputSpec: modules/openapi-generator/src/test/resources/2_0/petstore.yaml
+templateDir: modules/openapi-generator/src/main/resources/kotlin-spring
+additionalProperties:
+  documentationProvider: none
+  annotationLibrary: none
+  useSwaggerUI: "false"
+  serviceImplementation: "true"
+  serializableModel: "true"
+  beanValidations: "true"
+  useResponseEntity: "false"
+  requestMappingMode: controller

bin/configs/kotlin-spring-declarative-interface-reactive-coroutines.yaml

@@ -11,6 +11,6 @@ additionalProperties:
   beanValidations: "true"
   interfaceOnly: true
   reactive: true
-  declarativeInterfaceWrapResponses: false
+  useResponseEntity: false
   useFlowForArrayReturnType: false
   declarativeInterfaceReactiveMode: "coroutines"

bin/configs/kotlin-spring-declarative-interface-reactive-reactor-wrapped.yaml

@@ -11,6 +11,6 @@ additionalProperties:
   beanValidations: "true"
   interfaceOnly: true
   reactive: true
-  declarativeInterfaceWrapResponses: true
+  useResponseEntity: true
   useFlowForArrayReturnType: false
   declarativeInterfaceReactiveMode: "reactor"

bin/configs/kotlin-spring-declarative-interface-wrapped.yaml

@@ -11,5 +11,5 @@ additionalProperties:
   beanValidations: "true"
   interfaceOnly: true
   reactive: false
-  declarativeInterfaceWrapResponses: true
+  useResponseEntity: true
   useFlowForArrayReturnType: false

bin/configs/kotlin-spring-declarative-interface.yaml

@@ -11,5 +11,5 @@ additionalProperties:
   beanValidations: "true"
   interfaceOnly: true
   reactive: false
-  declarativeInterfaceWrapResponses: true
+  useResponseEntity: true
   useFlowForArrayReturnType: false

docs/generators/kotlin-spring.md

@@ -28,7 +28,6 @@ These options may be applied as additional-properties (cli) or configOptions (pl
 |beanQualifiers|Whether to add fully-qualifier class names as bean qualifiers in @Component and @RestController annotations. May be used to prevent bean names clash if multiple generated libraries (contexts) added to single project.| |false|
 |configPackage|configuration package for generated code| |org.openapitools.configuration|
 |declarativeInterfaceReactiveMode|What type of reactive style to use in Spring Http declarative interface|<dl><dt>**coroutines**</dt><dd>Use kotlin-idiomatic 'suspend' functions</dd><dt>**reactor**</dt><dd>Use reactor return wrappers 'Mono' and 'Flux'</dd></dl>|coroutines|
-|declarativeInterfaceWrapResponses|Whether (when false) to return actual type (e.g. List&lt;Fruit&gt;) and handle non 2xx responses via exceptions or (when true) return entire ResponseEntity (e.g. ResponseEntity&lt;List&lt;Fruit&gt;&gt;)| |false|
 |delegatePattern|Whether to generate the server files using the delegate pattern| |false|
 |documentationProvider|Select the OpenAPI documentation provider.|<dl><dt>**none**</dt><dd>Do not publish an OpenAPI specification.</dd><dt>**source**</dt><dd>Publish the original input OpenAPI specification.</dd><dt>**springfox**</dt><dd>Generate an OpenAPI 2 (fka Swagger RESTful API Documentation Specification) specification using SpringFox 2.x. Deprecated (for removal); use springdoc instead.</dd><dt>**springdoc**</dt><dd>Generate an OpenAPI 3 specification using SpringDoc.</dd></dl>|springdoc|
 |enumPropertyNaming|Naming convention for enum properties: 'camelCase', 'PascalCase', 'snake_case', 'UPPERCASE', and 'original'| |original|
@@ -56,6 +55,7 @@ These options may be applied as additional-properties (cli) or configOptions (pl
 |useBeanValidation|Use BeanValidation API annotations to validate data types| |true|
 |useFeignClientUrl|Whether to generate Feign client with url parameter.| |true|
 |useFlowForArrayReturnType|Whether to use Flow for array/collection return types when reactive is enabled. If false, will use List instead.| |true|
+|useResponseEntity|Whether (when false) to return actual type (e.g. List&lt;Fruit&gt;) and handle non-happy path responses via exceptions flow or (when true) return entire ResponseEntity (e.g. ResponseEntity&lt;List&lt;Fruit&gt;&gt;). If disabled, method are annotated using a @ResponseStatus annotation, which has the status of the first response declared in the Api definition| |true|
 |useSpringBoot3|Generate code and provide dependencies for use with Spring Boot 3.x. (Use jakarta instead of javax in imports). Enabling this option will also enable `useJakartaEe`.| |false|
 |useSwaggerUI|Open the OpenApi specification in swagger-ui. Will also import and configure needed dependencies| |true|
 |useTags|Whether to use tags for creating interface and controller class names| |false|