loafle/openapi-generator
3
0
Fork 0
forked from loafle/openapi-generator-original
Code Pull Requests Activity

[Kotlin-Spring] Support multiline descriptions (#14406)

Browse Source 
* [Kotlin-Spring] Support multiline descriptions

This commit adds support for multiline descriptions for operations in
the Kotlin-Spring generator, for both regular API generation (i.e.
Controller), as well as interface-only API generation.

Multiline descriptions allow us to use rich text representations, e.g.
with Markdown. Note that Markdown-formatted descriptions are rendered
nicely in Swagger-UI. I imagine that most openapi consumers will be able
(or will want to) support Markdown (at some point).

The solution for Kotlin-Spring is rather simple, using Raw Strings to
contain the `unescapedNotes`.

See: https://kotlinlang.org/docs/strings.html#raw-strings

Note that specific unescaped strings could cause problems. For example,
the string containing three double quotes `"""` would result in compile
errors for the generated code. I think this is acceptable.

Note that an improvement is possible to use `.trimMargin()` in
combination with the pipe symbol `|`, to allow specific margin
prefixing.

Note that the description is used in escaped form in the JavaDoc. This
could be resolved by prefixing every line of the unescapedNotes with a
star `*`.

For now, I've chosen to implement this the simplest way I could think
off.

Signed-off-by: Nico Korthout <nico.korthout@camunda.com>

* [Kotlin-Spring] Update samples

Signed-off-by: Nico Korthout <nico.korthout@camunda.com>

---------

Signed-off-by: Nico Korthout <nico.korthout@camunda.com>
This commit is contained in:
Nico Korthout
2023-02-07 18:25:12 +01:00
committed by GitHub
parent 515abf8c68
commit 26eb1dc805
16 changed files with 148 additions and 82 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
samples/server/petstore/kotlin-springboot-source-swagger2/src/main/kotlin/org/openapitools/api/PetApiController.kt
View File

@@ -30,7 +30,7 @@ class PetApiController(@Autowired(required = true) val service: PetApiService) {
@Operation(
summary = "Add a new pet to the store",
operationId = "addPet",
description = "",
description = """""",
responses = [
ApiResponse(responseCode = "405", description = "Invalid input") ],
security = [ SecurityRequirement(name = "petstore_auth", scopes = [ "write:pets", "read:pets" ]) ]
@@ -47,7 +47,7 @@ class PetApiController(@Autowired(required = true) val service: PetApiService) {
@Operation(
summary = "Deletes a pet",
operationId = "deletePet",
description = "",
description = """""",
responses = [
ApiResponse(responseCode = "400", description = "Invalid pet value") ],
security = [ SecurityRequirement(name = "petstore_auth", scopes = [ "write:pets", "read:pets" ]) ]
@@ -63,7 +63,7 @@ class PetApiController(@Autowired(required = true) val service: PetApiService) {
@Operation(
summary = "Finds Pets by status",
operationId = "findPetsByStatus",
description = "Multiple status values can be provided with comma separated strings",
description = """Multiple status values can be provided with comma separated strings""",
responses = [
ApiResponse(responseCode = "200", description = "successful operation", content = [Content(schema = Schema(implementation = Pet::class))]),
ApiResponse(responseCode = "400", description = "Invalid status value") ],
@@ -81,7 +81,7 @@ class PetApiController(@Autowired(required = true) val service: PetApiService) {
@Operation(
summary = "Finds Pets by tags",
operationId = "findPetsByTags",
description = "Multiple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing.",
description = """Multiple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing.""",
responses = [
ApiResponse(responseCode = "200", description = "successful operation", content = [Content(schema = Schema(implementation = Pet::class))]),
ApiResponse(responseCode = "400", description = "Invalid tag value") ],
@@ -99,7 +99,7 @@ class PetApiController(@Autowired(required = true) val service: PetApiService) {
@Operation(
summary = "Find pet by ID",
operationId = "getPetById",
description = "Returns a single pet",
description = """Returns a single pet""",
responses = [
ApiResponse(responseCode = "200", description = "successful operation", content = [Content(schema = Schema(implementation = Pet::class))]),
ApiResponse(responseCode = "400", description = "Invalid ID supplied"),
@@ -118,7 +118,7 @@ class PetApiController(@Autowired(required = true) val service: PetApiService) {
@Operation(
summary = "Update an existing pet",
operationId = "updatePet",
description = "",
description = """""",
responses = [
ApiResponse(responseCode = "400", description = "Invalid ID supplied"),
ApiResponse(responseCode = "404", description = "Pet not found"),
@@ -137,7 +137,7 @@ class PetApiController(@Autowired(required = true) val service: PetApiService) {
@Operation(
summary = "Updates a pet in the store with form data",
operationId = "updatePetWithForm",
description = "",
description = """""",
responses = [
ApiResponse(responseCode = "405", description = "Invalid input") ],
security = [ SecurityRequirement(name = "petstore_auth", scopes = [ "write:pets", "read:pets" ]) ]
@@ -154,7 +154,7 @@ class PetApiController(@Autowired(required = true) val service: PetApiService) {
@Operation(
summary = "uploads an image",
operationId = "uploadFile",
description = "",
description = """""",
responses = [
ApiResponse(responseCode = "200", description = "successful operation", content = [Content(schema = Schema(implementation = ModelApiResponse::class))]) ],
security = [ SecurityRequirement(name = "petstore_auth", scopes = [ "write:pets", "read:pets" ]) ]

8
samples/server/petstore/kotlin-springboot-source-swagger2/src/main/kotlin/org/openapitools/api/StoreApiController.kt
View File

@@ -29,7 +29,7 @@ class StoreApiController(@Autowired(required = true) val service: StoreApiServic
@Operation(
summary = "Delete purchase order by ID",
operationId = "deleteOrder",
description = "For valid response try integer IDs with value < 1000. Anything above 1000 or nonintegers will generate API errors",
description = """For valid response try integer IDs with value < 1000. Anything above 1000 or nonintegers will generate API errors""",
responses = [
ApiResponse(responseCode = "400", description = "Invalid ID supplied"),
ApiResponse(responseCode = "404", description = "Order not found") ]
@@ -45,7 +45,7 @@ class StoreApiController(@Autowired(required = true) val service: StoreApiServic
@Operation(
summary = "Returns pet inventories by status",
operationId = "getInventory",
description = "Returns a map of status codes to quantities",
description = """Returns a map of status codes to quantities""",
responses = [
ApiResponse(responseCode = "200", description = "successful operation", content = [Content(schema = Schema(implementation = kotlin.collections.Map::class))]) ],
security = [ SecurityRequirement(name = "api_key") ]
@@ -62,7 +62,7 @@ class StoreApiController(@Autowired(required = true) val service: StoreApiServic
@Operation(
summary = "Find purchase order by ID",
operationId = "getOrderById",
description = "For valid response try integer IDs with value <= 5 or > 10. Other values will generate exceptions",
description = """For valid response try integer IDs with value <= 5 or > 10. Other values will generate exceptions""",
responses = [
ApiResponse(responseCode = "200", description = "successful operation", content = [Content(schema = Schema(implementation = Order::class))]),
ApiResponse(responseCode = "400", description = "Invalid ID supplied"),
@@ -80,7 +80,7 @@ class StoreApiController(@Autowired(required = true) val service: StoreApiServic
@Operation(
summary = "Place an order for a pet",
operationId = "placeOrder",
description = "",
description = """""",
responses = [
ApiResponse(responseCode = "200", description = "successful operation", content = [Content(schema = Schema(implementation = Order::class))]),
ApiResponse(responseCode = "400", description = "Invalid Order") ]

16
samples/server/petstore/kotlin-springboot-source-swagger2/src/main/kotlin/org/openapitools/api/UserApiController.kt
View File

@@ -29,7 +29,7 @@ class UserApiController(@Autowired(required = true) val service: UserApiService)
@Operation(
summary = "Create user",
operationId = "createUser",
description = "This can only be done by the logged in user.",
description = """This can only be done by the logged in user.""",
responses = [
ApiResponse(responseCode = "200", description = "successful operation") ]
)
@@ -44,7 +44,7 @@ class UserApiController(@Autowired(required = true) val service: UserApiService)
@Operation(
summary = "Creates list of users with given input array",
operationId = "createUsersWithArrayInput",
description = "",
description = """""",
responses = [
ApiResponse(responseCode = "200", description = "successful operation") ]
)
@@ -59,7 +59,7 @@ class UserApiController(@Autowired(required = true) val service: UserApiService)
@Operation(
summary = "Creates list of users with given input array",
operationId = "createUsersWithListInput",
description = "",
description = """""",
responses = [
ApiResponse(responseCode = "200", description = "successful operation") ]
)
@@ -74,7 +74,7 @@ class UserApiController(@Autowired(required = true) val service: UserApiService)
@Operation(
summary = "Delete user",
operationId = "deleteUser",
description = "This can only be done by the logged in user.",
description = """This can only be done by the logged in user.""",
responses = [
ApiResponse(responseCode = "400", description = "Invalid username supplied"),
ApiResponse(responseCode = "404", description = "User not found") ]
@@ -90,7 +90,7 @@ class UserApiController(@Autowired(required = true) val service: UserApiService)
@Operation(
summary = "Get user by user name",
operationId = "getUserByName",
description = "",
description = """""",
responses = [
ApiResponse(responseCode = "200", description = "successful operation", content = [Content(schema = Schema(implementation = User::class))]),
ApiResponse(responseCode = "400", description = "Invalid username supplied"),
@@ -108,7 +108,7 @@ class UserApiController(@Autowired(required = true) val service: UserApiService)
@Operation(
summary = "Logs user into the system",
operationId = "loginUser",
description = "",
description = """""",
responses = [
ApiResponse(responseCode = "200", description = "successful operation", content = [Content(schema = Schema(implementation = kotlin.String::class))]),
ApiResponse(responseCode = "400", description = "Invalid username/password supplied") ]
@@ -125,7 +125,7 @@ class UserApiController(@Autowired(required = true) val service: UserApiService)
@Operation(
summary = "Logs out current logged in user session",
operationId = "logoutUser",
description = "",
description = """""",
responses = [
ApiResponse(responseCode = "200", description = "successful operation") ]
)
@@ -140,7 +140,7 @@ class UserApiController(@Autowired(required = true) val service: UserApiService)
@Operation(
summary = "Updated user",
operationId = "updateUser",
description = "This can only be done by the logged in user.",
description = """This can only be done by the logged in user.""",
responses = [
ApiResponse(responseCode = "400", description = "Invalid user supplied"),
ApiResponse(responseCode = "404", description = "User not found") ]