[kotlin-spring] Adding DocumentationProvider and SwaggerUI (#12184)

* Adding DocumentationProvider and SwaggerUI to Kotlin Spring

* Fixing annotation errors

* Fixes to homeController

* Minor stylistic fixes

* Removing parameter from docs

* Structuring pom, making gradle file similar to pom

* Updating samples

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

@@ -21,9 +21,12 @@ jobs:
         sample:
           # server
           - samples/server/petstore/kotlin-springboot
-          - samples/server/petstore/kotlin-springboot-modelMutable
           - samples/server/petstore/kotlin-springboot-delegate
+          - samples/server/petstore/kotlin-springboot-modelMutable
           - samples/server/petstore/kotlin-springboot-reactive
+          - samples/server/petstore/kotlin-springboot-source-swagger1
+          - samples/server/petstore/kotlin-springboot-source-swagger2
+          - samples/server/petstore/kotlin-springboot-springfox
           - samples/server/petstore/kotlin-server/ktor
           - samples/server/petstore/kotlin-server/jaxrs-spec
           - samples/server/petstore/kotlin-server-modelMutable

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

@@ -4,6 +4,8 @@ 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: springdoc
+  annotationLibrary: swagger2
+  useSwaggerUI: "true"
   delegatePattern: "true"
-  swaggerAnnotations: "true"
   beanValidations: "true"

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

@@ -4,8 +4,10 @@ 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: springdoc
+  annotationLibrary: swagger2
+  useSwaggerUI: "true"
   serializableModel: "true"
-  swaggerAnnotations: "true"
   serviceImplementation: "true"
   beanValidations: "true"
   modelMutable: "true"

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

@@ -4,7 +4,9 @@ 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: springdoc
+  annotationLibrary: swagger2
+  useSwaggerUI: "true"
   serviceImplementation: "true"
   reactive: "true"
-  swaggerAnnotations: "true"
   beanValidations: "true"

bin/configs/kotlin-spring-boot-source-swagger1.yaml

@@ -0,0 +1,12 @@
+generatorName: kotlin-spring
+outputDir: samples/server/petstore/kotlin-springboot-source-swagger1
+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: source
+  annotationLibrary: swagger1
+  useSwaggerUI: "true"
+  serviceImplementation: "true"
+  serializableModel: "true"
+  beanValidations: "true"

bin/configs/kotlin-spring-boot-source-swagger2.yaml

@@ -0,0 +1,12 @@
+generatorName: kotlin-spring
+outputDir: samples/server/petstore/kotlin-springboot-source-swagger2
+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: source
+  annotationLibrary: swagger2
+  useSwaggerUI: "true"
+  serviceImplementation: "true"
+  serializableModel: "true"
+  beanValidations: "true"

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

@@ -0,0 +1,12 @@
+generatorName: kotlin-spring
+outputDir: samples/server/petstore/kotlin-springboot-springfox
+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: springfox
+  annotationLibrary: swagger1
+  useSwaggerUI: "true"
+  serviceImplementation: "true"
+  serializableModel: "true"
+  beanValidations: "true"

bin/configs/kotlin-spring-boot.yaml

@@ -4,7 +4,9 @@ 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"
-  swaggerAnnotations: "true"
   beanValidations: "true"

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

@@ -4,7 +4,9 @@ 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: springdoc
+  annotationLibrary: swagger2
+  useSwaggerUI: "true"
   serviceImplementation: "true"
   reactive: "true"
-  swaggerAnnotations: "true"
   beanValidations: "true"

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

@@ -4,7 +4,9 @@ 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"
-  swaggerAnnotations: "true"
   beanValidations: "true"

docs/generators/kotlin-spring.md

@@ -18,13 +18,15 @@ These options may be applied as additional-properties (cli) or configOptions (pl
 
 | Option | Description | Values | Default |
 | ------ | ----------- | ------ | ------- |
+|annotationLibrary|Select the complementary documentation annotation library.|<dl><dt>**none**</dt><dd>Do not annotate Model and Api with complementary annotations.</dd><dt>**swagger1**</dt><dd>Annotate Model and Api using the Swagger Annotations 1.x library.</dd><dt>**swagger2**</dt><dd>Annotate Model and Api using the Swagger Annotations 2.x library.</dd></dl>|swagger2|
 |apiPackage|api package for generated code| |org.openapitools.api|
 |apiSuffix|suffix for api classes| |Api|
 |artifactId|Generated artifact id (name of jar).| |openapi-spring|
 |artifactVersion|Generated artifact's package version.| |1.0.0|
 |basePackage|base package (invokerPackage) for generated code| |org.openapitools|
 |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|
 |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'| |camelCase|
 |exceptionHandler|generate default global exception handlers (not compatible with reactive. enabling reactive will disable exceptionHandler )| |true|
 |gradleBuildFile|generate a gradle build file using the Kotlin DSL| |true|
@@ -44,9 +46,9 @@ These options may be applied as additional-properties (cli) or configOptions (pl
 |sortModelPropertiesByRequiredFlag|Sort model properties to place required parameters before optional parameters.| |null|
 |sortParamsByRequiredFlag|Sort method arguments to place required parameters before optional parameters.| |null|
 |sourceFolder|source folder for generated code| |src/main/kotlin|
-|swaggerAnnotations|generate swagger annotations to go alongside controllers and models| |false|
 |title|server title name or client service name| |OpenAPI Kotlin Spring|
 |useBeanValidation|Use BeanValidation API annotations to validate data types| |true|
+|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|
 
 ## IMPORT MAPPING

docs/usage.md

@@ -555,7 +555,7 @@ openapi-generator-cli generate \
     -i petstore.yaml \
     -g kotlin-spring \
     -o out \
-    --additional-properties=library=spring-boot,beanValidations=true,swaggerAnnotations=true,serviceImplementation=true \
+    --additional-properties=library=spring-boot,beanValidations=true,serviceImplementation=true \
     --import-mappings=DateTime=java.time.LocalDateTime \
     --type-mappings=DateTime=java.time.LocalDateTime
 ```