fix(kotlin-server): emit KDoc for operation summary and description in jaxrs-spec interfaces

modules/openapi-generator/src/main/resources/kotlin-server/libraries/jaxrs-spec/apiInterface.mustache

@@ -1,3 +1,19 @@
+    {{#summary}}
+    /**
+     * {{{summary}}}
+    {{#notes}}
+     *
+     * {{{notes}}}
+    {{/notes}}
+{{>operationDoc}}
+    {{/summary}}
+    {{^summary}}
+    {{#notes}}
+    /**
+     * {{{notes}}}
+{{>operationDoc}}
+    {{/notes}}
+    {{/summary}}
     @{{httpMethod}}{{#subresourceOperation}}
     @Path("{{{path}}}"){{/subresourceOperation}}{{#hasConsumes}}
     @Consumes({{#consumes}}"{{{mediaType}}}"{{^-last}}, {{/-last}}{{/consumes}}){{/hasConsumes}}{{#hasProduces}}

modules/openapi-generator/src/main/resources/kotlin-server/libraries/jaxrs-spec/operationDoc.mustache

@@ -0,0 +1,13 @@
+{{#allParams}}
+{{#description}}
+     * @param {{paramName}}{{#isFormParam}}{{#isFile}}InputStream{{/isFile}}{{/isFormParam}} {{{description}}}
+{{/description}}
+{{/allParams}}
+{{#responses.0}}
+     * @return {{#responses}}{{{message}}} (status code {{code}}){{^-last}}
+     *         or {{/-last}}{{/responses}}
+{{/responses.0}}
+{{#isDeprecated}}
+     * @deprecated
+{{/isDeprecated}}
+     */

samples/server/others/kotlin-server/jaxrs-spec-array-response/src/main/kotlin/org/openapitools/server/apis/StuffApi.kt

@@ -14,11 +14,25 @@ import java.io.InputStream
 @jakarta.annotation.Generated(value = arrayOf("org.openapitools.codegen.languages.KotlinServerCodegen"), comments = "Generator version: 7.26.0-SNAPSHOT")
 interface StuffApi {
 
+    /**
+     * Finds stuff
+     *
+     * Finds stuff
+     * @return successful operation (status code 200)
+     *         or Invalid status value (status code 400)
+     */
     @GET
     @Path("/stuff")
     @Produces("application/json")
     fun findStuff(): kotlin.collections.List<Stuff>
 
+    /**
+     * Finds unique stuff
+     *
+     * Finds unique stuff
+     * @return successful operation (status code 200)
+     *         or Invalid status value (status code 400)
+     */
     @GET
     @Path("/uniquestuff")
     @Produces("application/json")

samples/server/petstore/kotlin-server/jaxrs-spec-mutiny/src/main/kotlin/org/openapitools/server/apis/PetApi.kt

@@ -15,38 +15,95 @@ import java.io.InputStream
 @javax.annotation.Generated(value = arrayOf("org.openapitools.codegen.languages.KotlinServerCodegen"), comments = "Generator version: 7.26.0-SNAPSHOT")
 interface PetApi {
 
+    /**
+     * Add a new pet to the store
+     * @param body Pet object that needs to be added to the store
+     * @return Invalid input (status code 405)
+     */
     @POST
     @Consumes("application/json", "application/xml")
     fun addPet( body: Pet): io.smallrye.mutiny.Uni<Response>
 
+    /**
+     * Deletes a pet
+     * @param petId Pet id to delete
+     * @return Invalid pet value (status code 400)
+     */
     @DELETE
     @Path("/{petId}")
     fun deletePet(@PathParam("petId") petId: kotlin.Long,@HeaderParam("api_key")  apiKey: kotlin.String?): io.smallrye.mutiny.Uni<Response>
 
+    /**
+     * 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
+     * @return successful operation (status code 200)
+     *         or Invalid status value (status code 400)
+     */
     @GET
     @Path("/findByStatus")
     @Produces("application/xml", "application/json")
     fun findPetsByStatus(@QueryParam("status") status: kotlin.collections.List<kotlin.String>): io.smallrye.mutiny.Uni<Response>
 
+    /**
+     * 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
+     * @return successful operation (status code 200)
+     *         or Invalid tag value (status code 400)
+     * @deprecated
+     */
     @GET
     @Path("/findByTags")
     @Produces("application/xml", "application/json")
     fun findPetsByTags(@QueryParam("tags") tags: kotlin.collections.List<kotlin.String>): io.smallrye.mutiny.Uni<Response>
 
+    /**
+     * Find pet by ID
+     *
+     * Returns a single pet
+     * @param petId ID of pet to return
+     * @return successful operation (status code 200)
+     *         or Invalid ID supplied (status code 400)
+     *         or Pet not found (status code 404)
+     */
     @GET
     @Path("/{petId}")
     @Produces("application/xml", "application/json")
     fun getPetById(@PathParam("petId") petId: kotlin.Long): io.smallrye.mutiny.Uni<Response>
 
+    /**
+     * Update an existing pet
+     * @param body Pet object that needs to be added to the store
+     * @return Invalid ID supplied (status code 400)
+     *         or Pet not found (status code 404)
+     *         or Validation exception (status code 405)
+     */
     @PUT
     @Consumes("application/json", "application/xml")
     fun updatePet( body: Pet): io.smallrye.mutiny.Uni<Response>
 
+    /**
+     * Updates a pet in the store with form data
+     * @param petId ID of pet that needs to be updated
+     * @param name Updated name of the pet
+     * @param status Updated status of the pet
+     * @return Invalid input (status code 405)
+     */
     @POST
     @Path("/{petId}")
     @Consumes("application/x-www-form-urlencoded")
     fun updatePetWithForm(@PathParam("petId") petId: kotlin.Long,@FormParam(value = "name") name: kotlin.String?,@FormParam(value = "status") status: kotlin.String?): io.smallrye.mutiny.Uni<Response>
 
+    /**
+     * uploads an image
+     * @param petId ID of pet to update
+     * @param additionalMetadata Additional data to pass to server
+     * @param fileInputStream file to upload
+     * @return successful operation (status code 200)
+     */
     @POST
     @Path("/{petId}/uploadImage")
     @Consumes("multipart/form-data")

samples/server/petstore/kotlin-server/jaxrs-spec-mutiny/src/main/kotlin/org/openapitools/server/apis/StoreApi.kt

@@ -14,20 +14,49 @@ import java.io.InputStream
 @javax.annotation.Generated(value = arrayOf("org.openapitools.codegen.languages.KotlinServerCodegen"), comments = "Generator version: 7.26.0-SNAPSHOT")
 interface StoreApi {
 
+    /**
+     * 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
+     * @return Invalid ID supplied (status code 400)
+     *         or Order not found (status code 404)
+     */
     @DELETE
     @Path("/order/{orderId}")
     fun deleteOrder(@PathParam("orderId") orderId: kotlin.String): io.smallrye.mutiny.Uni<Response>
 
+    /**
+     * Returns pet inventories by status
+     *
+     * Returns a map of status codes to quantities
+     * @return successful operation (status code 200)
+     */
     @GET
     @Path("/inventory")
     @Produces("application/json")
     fun getInventory(): io.smallrye.mutiny.Uni<Response>
 
+    /**
+     * Find purchase order by ID
+     *
+     * For valid response try integer IDs with value <= 5 or > 10. Other values will generate exceptions
+     * @param orderId ID of pet that needs to be fetched
+     * @return successful operation (status code 200)
+     *         or Invalid ID supplied (status code 400)
+     *         or Order not found (status code 404)
+     */
     @GET
     @Path("/order/{orderId}")
     @Produces("application/xml", "application/json")
     fun getOrderById(@PathParam("orderId") orderId: kotlin.Long): io.smallrye.mutiny.Uni<Response>
 
+    /**
+     * Place an order for a pet
+     * @param body order placed for purchasing the pet
+     * @return successful operation (status code 200)
+     *         or Invalid Order (status code 400)
+     */
     @POST
     @Path("/order")
     @Produces("application/xml", "application/json")

samples/server/petstore/kotlin-server/jaxrs-spec-mutiny/src/main/kotlin/org/openapitools/server/apis/UserApi.kt

@@ -14,35 +14,87 @@ import java.io.InputStream
 @javax.annotation.Generated(value = arrayOf("org.openapitools.codegen.languages.KotlinServerCodegen"), comments = "Generator version: 7.26.0-SNAPSHOT")
 interface UserApi {
 
+    /**
+     * Create user
+     *
+     * This can only be done by the logged in user.
+     * @param body Created user object
+     * @return successful operation (status code 0)
+     */
     @POST
     fun createUser( body: User): io.smallrye.mutiny.Uni<Response>
 
+    /**
+     * Creates list of users with given input array
+     * @param body List of user object
+     * @return successful operation (status code 0)
+     */
     @POST
     @Path("/createWithArray")
     fun createUsersWithArrayInput( body: kotlin.collections.List<User>): io.smallrye.mutiny.Uni<Response>
 
+    /**
+     * Creates list of users with given input array
+     * @param body List of user object
+     * @return successful operation (status code 0)
+     */
     @POST
     @Path("/createWithList")
     fun createUsersWithListInput( body: kotlin.collections.List<User>): io.smallrye.mutiny.Uni<Response>
 
+    /**
+     * Delete user
+     *
+     * This can only be done by the logged in user.
+     * @param username The name that needs to be deleted
+     * @return Invalid username supplied (status code 400)
+     *         or User not found (status code 404)
+     */
     @DELETE
     @Path("/{username}")
     fun deleteUser(@PathParam("username") username: kotlin.String): io.smallrye.mutiny.Uni<Response>
 
+    /**
+     * Get user by user name
+     * @param username The name that needs to be fetched. Use user1 for testing.
+     * @return successful operation (status code 200)
+     *         or Invalid username supplied (status code 400)
+     *         or User not found (status code 404)
+     */
     @GET
     @Path("/{username}")
     @Produces("application/xml", "application/json")
     fun getUserByName(@PathParam("username") username: kotlin.String): io.smallrye.mutiny.Uni<Response>
 
+    /**
+     * Logs user into the system
+     * @param username The user name for login
+     * @param password The password for login in clear text
+     * @return successful operation (status code 200)
+     *         or Invalid username/password supplied (status code 400)
+     */
     @GET
     @Path("/login")
     @Produces("application/xml", "application/json")
     fun loginUser(@QueryParam("username") username: kotlin.String,@QueryParam("password") password: kotlin.String): io.smallrye.mutiny.Uni<Response>
 
+    /**
+     * Logs out current logged in user session
+     * @return successful operation (status code 0)
+     */
     @GET
     @Path("/logout")
     fun logoutUser(): io.smallrye.mutiny.Uni<Response>
 
+    /**
+     * Updated user
+     *
+     * This can only be done by the logged in user.
+     * @param username name that need to be deleted
+     * @param body Updated user object
+     * @return Invalid user supplied (status code 400)
+     *         or User not found (status code 404)
+     */
     @PUT
     @Path("/{username}")
     fun updateUser(@PathParam("username") username: kotlin.String, body: User): io.smallrye.mutiny.Uni<Response>