[kotlin-spring] add comment to api method (#10857)

* fix: add api comment

* update sample

* update sample

modules/openapi-generator/src/main/resources/kotlin-spring/service.mustache

@@ -10,6 +10,26 @@ import kotlinx.coroutines.flow.Flow;
 interface {{classname}}Service {
 {{#operation}}
 
+    /**
+     * {{httpMethod}} {{{path}}}{{#summary}} : {{.}}{{/summary}}
+    {{#notes}}
+     * {{.}}
+    {{/notes}}
+     *
+    {{#allParams}}
+     * @param {{paramName}} {{description}}{{#required}} (required){{/required}}{{^required}} (optional{{#defaultValue}}, default to {{.}}{{/defaultValue}}){{/required}}
+    {{/allParams}}
+     * @return {{#responses}}{{message}} (status code {{code}}){{^-last}}
+     *         or {{/-last}}{{/responses}}
+    {{#isDeprecated}}
+     * @deprecated
+    {{/isDeprecated}}
+    {{#externalDocs}}
+     * {{description}}
+     * @see <a href="{{url}}">{{summary}} Documentation</a>
+    {{/externalDocs}}
+     * @see {{classname}}#{{operationId}}
+     */
     {{#reactive}}{{^isArray}}suspend {{/isArray}}{{/reactive}}fun {{operationId}}({{#allParams}}{{paramName}}: {{^isBodyParam}}{{>optionalDataType}}{{/isBodyParam}}{{#isBodyParam}}{{^reactive}}{{>optionalDataType}}{{/reactive}}{{#reactive}}{{^isArray}}{{>optionalDataType}}{{/isArray}}{{#isArray}}Flow<{{{baseType}}}>{{/isArray}}{{/reactive}}{{/isBodyParam}}{{^-last}}, {{/-last}}{{/allParams}}): {{>returnTypes}}
 {{/operation}}
 }

samples/server/petstore/kotlin-springboot-reactive/src/main/kotlin/org/openapitools/api/PetApiService.kt

@@ -6,19 +6,90 @@ import kotlinx.coroutines.flow.Flow;
 
 interface PetApiService {
 
+    /**
+     * POST /pet : Add a new pet to the store
+     *
+     * @param body Pet object that needs to be added to the store (required)
+     * @return Invalid input (status code 405)
+     * @see PetApi#addPet
+     */
     suspend fun addPet(body: Pet): Unit
 
+    /**
+     * DELETE /pet/{petId} : Deletes a pet
+     *
+     * @param petId Pet id to delete (required)
+     * @param apiKey  (optional)
+     * @return Invalid pet value (status code 400)
+     * @see PetApi#deletePet
+     */
     suspend fun deletePet(petId: kotlin.Long, apiKey: kotlin.String?): Unit
 
+    /**
+     * GET /pet/findByStatus : Finds Pets by status
+     * Multiple status values can be provided with comma separated strings
+     *
+     * @param status Status values that need to be considered for filter (required)
+     * @return successful operation (status code 200)
+     *         or Invalid status value (status code 400)
+     * @see PetApi#findPetsByStatus
+     */
     fun findPetsByStatus(status: kotlin.collections.List<kotlin.String>): Flow<Pet>
 
+    /**
+     * GET /pet/findByTags : Finds Pets by tags
+     * Multiple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing.
+     *
+     * @param tags Tags to filter by (required)
+     * @return successful operation (status code 200)
+     *         or Invalid tag value (status code 400)
+     * @deprecated
+     * @see PetApi#findPetsByTags
+     */
     fun findPetsByTags(tags: kotlin.collections.List<kotlin.String>): Flow<Pet>
 
+    /**
+     * GET /pet/{petId} : Find pet by ID
+     * Returns a single pet
+     *
+     * @param petId ID of pet to return (required)
+     * @return successful operation (status code 200)
+     *         or Invalid ID supplied (status code 400)
+     *         or Pet not found (status code 404)
+     * @see PetApi#getPetById
+     */
     suspend fun getPetById(petId: kotlin.Long): Pet
 
+    /**
+     * PUT /pet : Update an existing pet
+     *
+     * @param body Pet object that needs to be added to the store (required)
+     * @return Invalid ID supplied (status code 400)
+     *         or Pet not found (status code 404)
+     *         or Validation exception (status code 405)
+     * @see PetApi#updatePet
+     */
     suspend fun updatePet(body: Pet): Unit
 
+    /**
+     * POST /pet/{petId} : Updates a pet in the store with form data
+     *
+     * @param petId ID of pet that needs to be updated (required)
+     * @param name Updated name of the pet (optional)
+     * @param status Updated status of the pet (optional)
+     * @return Invalid input (status code 405)
+     * @see PetApi#updatePetWithForm
+     */
     suspend fun updatePetWithForm(petId: kotlin.Long, name: kotlin.String?, status: kotlin.String?): Unit
 
+    /**
+     * POST /pet/{petId}/uploadImage : uploads an image
+     *
+     * @param petId ID of pet to update (required)
+     * @param additionalMetadata Additional data to pass to server (optional)
+     * @param file file to upload (optional)
+     * @return successful operation (status code 200)
+     * @see PetApi#uploadFile
+     */
     suspend fun uploadFile(petId: kotlin.Long, additionalMetadata: kotlin.String?, file: org.springframework.core.io.Resource?): ModelApiResponse
 }

samples/server/petstore/kotlin-springboot-reactive/src/main/kotlin/org/openapitools/api/StoreApiService.kt

@@ -5,11 +5,45 @@ import kotlinx.coroutines.flow.Flow;
 
 interface StoreApiService {
 
+    /**
+     * DELETE /store/order/{orderId} : Delete purchase order by ID
+     * For valid response try integer IDs with value < 1000. Anything above 1000 or nonintegers will generate API errors
+     *
+     * @param orderId ID of the order that needs to be deleted (required)
+     * @return Invalid ID supplied (status code 400)
+     *         or Order not found (status code 404)
+     * @see StoreApi#deleteOrder
+     */
     suspend fun deleteOrder(orderId: kotlin.String): Unit
 
+    /**
+     * GET /store/inventory : Returns pet inventories by status
+     * Returns a map of status codes to quantities
+     *
+     * @return successful operation (status code 200)
+     * @see StoreApi#getInventory
+     */
     suspend fun getInventory(): Map<String, kotlin.Int>
 
+    /**
+     * GET /store/order/{orderId} : Find purchase order by ID
+     * For valid response try integer IDs with value &lt;&#x3D; 5 or &gt; 10. Other values will generated exceptions
+     *
+     * @param orderId ID of pet that needs to be fetched (required)
+     * @return successful operation (status code 200)
+     *         or Invalid ID supplied (status code 400)
+     *         or Order not found (status code 404)
+     * @see StoreApi#getOrderById
+     */
     suspend fun getOrderById(orderId: kotlin.Long): Order
 
+    /**
+     * POST /store/order : Place an order for a pet
+     *
+     * @param body order placed for purchasing the pet (required)
+     * @return successful operation (status code 200)
+     *         or Invalid Order (status code 400)
+     * @see StoreApi#placeOrder
+     */
     suspend fun placeOrder(body: Order): Order
 }

samples/server/petstore/kotlin-springboot-reactive/src/main/kotlin/org/openapitools/api/UserApiService.kt

@@ -5,19 +5,84 @@ import kotlinx.coroutines.flow.Flow;
 
 interface UserApiService {
 
+    /**
+     * POST /user : Create user
+     * This can only be done by the logged in user.
+     *
+     * @param body Created user object (required)
+     * @return successful operation (status code 200)
+     * @see UserApi#createUser
+     */
     suspend fun createUser(body: User): Unit
 
+    /**
+     * POST /user/createWithArray : Creates list of users with given input array
+     *
+     * @param body List of user object (required)
+     * @return successful operation (status code 200)
+     * @see UserApi#createUsersWithArrayInput
+     */
     suspend fun createUsersWithArrayInput(body: Flow<User>): Unit
 
+    /**
+     * POST /user/createWithList : Creates list of users with given input array
+     *
+     * @param body List of user object (required)
+     * @return successful operation (status code 200)
+     * @see UserApi#createUsersWithListInput
+     */
     suspend fun createUsersWithListInput(body: Flow<User>): Unit
 
+    /**
+     * DELETE /user/{username} : Delete user
+     * This can only be done by the logged in user.
+     *
+     * @param username The name that needs to be deleted (required)
+     * @return Invalid username supplied (status code 400)
+     *         or User not found (status code 404)
+     * @see UserApi#deleteUser
+     */
     suspend fun deleteUser(username: kotlin.String): Unit
 
+    /**
+     * GET /user/{username} : Get user by user name
+     *
+     * @param username The name that needs to be fetched. Use user1 for testing. (required)
+     * @return successful operation (status code 200)
+     *         or Invalid username supplied (status code 400)
+     *         or User not found (status code 404)
+     * @see UserApi#getUserByName
+     */
     suspend fun getUserByName(username: kotlin.String): User
 
+    /**
+     * GET /user/login : Logs user into the system
+     *
+     * @param username The user name for login (required)
+     * @param password The password for login in clear text (required)
+     * @return successful operation (status code 200)
+     *         or Invalid username/password supplied (status code 400)
+     * @see UserApi#loginUser
+     */
     suspend fun loginUser(username: kotlin.String, password: kotlin.String): kotlin.String
 
+    /**
+     * GET /user/logout : Logs out current logged in user session
+     *
+     * @return successful operation (status code 200)
+     * @see UserApi#logoutUser
+     */
     suspend fun logoutUser(): Unit
 
+    /**
+     * PUT /user/{username} : Updated user
+     * This can only be done by the logged in user.
+     *
+     * @param username name that need to be deleted (required)
+     * @param body Updated user object (required)
+     * @return Invalid user supplied (status code 400)
+     *         or User not found (status code 404)
+     * @see UserApi#updateUser
+     */
     suspend fun updateUser(username: kotlin.String, body: User): Unit
 }

samples/server/petstore/kotlin-springboot/src/main/kotlin/org/openapitools/api/PetApiService.kt

@@ -5,19 +5,90 @@ import org.openapitools.model.Pet
 
 interface PetApiService {
 
+    /**
+     * POST /pet : Add a new pet to the store
+     *
+     * @param body Pet object that needs to be added to the store (required)
+     * @return Invalid input (status code 405)
+     * @see PetApi#addPet
+     */
     fun addPet(body: Pet): Unit
 
+    /**
+     * DELETE /pet/{petId} : Deletes a pet
+     *
+     * @param petId Pet id to delete (required)
+     * @param apiKey  (optional)
+     * @return Invalid pet value (status code 400)
+     * @see PetApi#deletePet
+     */
     fun deletePet(petId: kotlin.Long, apiKey: kotlin.String?): Unit
 
+    /**
+     * GET /pet/findByStatus : Finds Pets by status
+     * Multiple status values can be provided with comma separated strings
+     *
+     * @param status Status values that need to be considered for filter (required)
+     * @return successful operation (status code 200)
+     *         or Invalid status value (status code 400)
+     * @see PetApi#findPetsByStatus
+     */
     fun findPetsByStatus(status: kotlin.collections.List<kotlin.String>): List<Pet>
 
+    /**
+     * GET /pet/findByTags : Finds Pets by tags
+     * Multiple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing.
+     *
+     * @param tags Tags to filter by (required)
+     * @return successful operation (status code 200)
+     *         or Invalid tag value (status code 400)
+     * @deprecated
+     * @see PetApi#findPetsByTags
+     */
     fun findPetsByTags(tags: kotlin.collections.List<kotlin.String>): List<Pet>
 
+    /**
+     * GET /pet/{petId} : Find pet by ID
+     * Returns a single pet
+     *
+     * @param petId ID of pet to return (required)
+     * @return successful operation (status code 200)
+     *         or Invalid ID supplied (status code 400)
+     *         or Pet not found (status code 404)
+     * @see PetApi#getPetById
+     */
     fun getPetById(petId: kotlin.Long): Pet
 
+    /**
+     * PUT /pet : Update an existing pet
+     *
+     * @param body Pet object that needs to be added to the store (required)
+     * @return Invalid ID supplied (status code 400)
+     *         or Pet not found (status code 404)
+     *         or Validation exception (status code 405)
+     * @see PetApi#updatePet
+     */
     fun updatePet(body: Pet): Unit
 
+    /**
+     * POST /pet/{petId} : Updates a pet in the store with form data
+     *
+     * @param petId ID of pet that needs to be updated (required)
+     * @param name Updated name of the pet (optional)
+     * @param status Updated status of the pet (optional)
+     * @return Invalid input (status code 405)
+     * @see PetApi#updatePetWithForm
+     */
     fun updatePetWithForm(petId: kotlin.Long, name: kotlin.String?, status: kotlin.String?): Unit
 
+    /**
+     * POST /pet/{petId}/uploadImage : uploads an image
+     *
+     * @param petId ID of pet to update (required)
+     * @param additionalMetadata Additional data to pass to server (optional)
+     * @param file file to upload (optional)
+     * @return successful operation (status code 200)
+     * @see PetApi#uploadFile
+     */
     fun uploadFile(petId: kotlin.Long, additionalMetadata: kotlin.String?, file: org.springframework.core.io.Resource?): ModelApiResponse
 }

samples/server/petstore/kotlin-springboot/src/main/kotlin/org/openapitools/api/StoreApiService.kt

@@ -4,11 +4,45 @@ import org.openapitools.model.Order
 
 interface StoreApiService {
 
+    /**
+     * DELETE /store/order/{orderId} : Delete purchase order by ID
+     * For valid response try integer IDs with value < 1000. Anything above 1000 or nonintegers will generate API errors
+     *
+     * @param orderId ID of the order that needs to be deleted (required)
+     * @return Invalid ID supplied (status code 400)
+     *         or Order not found (status code 404)
+     * @see StoreApi#deleteOrder
+     */
     fun deleteOrder(orderId: kotlin.String): Unit
 
+    /**
+     * GET /store/inventory : Returns pet inventories by status
+     * Returns a map of status codes to quantities
+     *
+     * @return successful operation (status code 200)
+     * @see StoreApi#getInventory
+     */
     fun getInventory(): Map<String, kotlin.Int>
 
+    /**
+     * GET /store/order/{orderId} : Find purchase order by ID
+     * For valid response try integer IDs with value &lt;&#x3D; 5 or &gt; 10. Other values will generated exceptions
+     *
+     * @param orderId ID of pet that needs to be fetched (required)
+     * @return successful operation (status code 200)
+     *         or Invalid ID supplied (status code 400)
+     *         or Order not found (status code 404)
+     * @see StoreApi#getOrderById
+     */
     fun getOrderById(orderId: kotlin.Long): Order
 
+    /**
+     * POST /store/order : Place an order for a pet
+     *
+     * @param body order placed for purchasing the pet (required)
+     * @return successful operation (status code 200)
+     *         or Invalid Order (status code 400)
+     * @see StoreApi#placeOrder
+     */
     fun placeOrder(body: Order): Order
 }

samples/server/petstore/kotlin-springboot/src/main/kotlin/org/openapitools/api/UserApiService.kt

@@ -4,19 +4,84 @@ import org.openapitools.model.User
 
 interface UserApiService {
 
+    /**
+     * POST /user : Create user
+     * This can only be done by the logged in user.
+     *
+     * @param body Created user object (required)
+     * @return successful operation (status code 200)
+     * @see UserApi#createUser
+     */
     fun createUser(body: User): Unit
 
+    /**
+     * POST /user/createWithArray : Creates list of users with given input array
+     *
+     * @param body List of user object (required)
+     * @return successful operation (status code 200)
+     * @see UserApi#createUsersWithArrayInput
+     */
     fun createUsersWithArrayInput(body: kotlin.collections.List<User>): Unit
 
+    /**
+     * POST /user/createWithList : Creates list of users with given input array
+     *
+     * @param body List of user object (required)
+     * @return successful operation (status code 200)
+     * @see UserApi#createUsersWithListInput
+     */
     fun createUsersWithListInput(body: kotlin.collections.List<User>): Unit
 
+    /**
+     * DELETE /user/{username} : Delete user
+     * This can only be done by the logged in user.
+     *
+     * @param username The name that needs to be deleted (required)
+     * @return Invalid username supplied (status code 400)
+     *         or User not found (status code 404)
+     * @see UserApi#deleteUser
+     */
     fun deleteUser(username: kotlin.String): Unit
 
+    /**
+     * GET /user/{username} : Get user by user name
+     *
+     * @param username The name that needs to be fetched. Use user1 for testing. (required)
+     * @return successful operation (status code 200)
+     *         or Invalid username supplied (status code 400)
+     *         or User not found (status code 404)
+     * @see UserApi#getUserByName
+     */
     fun getUserByName(username: kotlin.String): User
 
+    /**
+     * GET /user/login : Logs user into the system
+     *
+     * @param username The user name for login (required)
+     * @param password The password for login in clear text (required)
+     * @return successful operation (status code 200)
+     *         or Invalid username/password supplied (status code 400)
+     * @see UserApi#loginUser
+     */
     fun loginUser(username: kotlin.String, password: kotlin.String): kotlin.String
 
+    /**
+     * GET /user/logout : Logs out current logged in user session
+     *
+     * @return successful operation (status code 200)
+     * @see UserApi#logoutUser
+     */
     fun logoutUser(): Unit
 
+    /**
+     * PUT /user/{username} : Updated user
+     * This can only be done by the logged in user.
+     *
+     * @param username name that need to be deleted (required)
+     * @param body Updated user object (required)
+     * @return Invalid user supplied (status code 400)
+     *         or User not found (status code 404)
+     * @see UserApi#updateUser
+     */
     fun updateUser(username: kotlin.String, body: User): Unit
 }