[BUG] [kotlin-server] [jaxrs-spec] interfaceOnly API interface does not emit summary/description as KDoc

[rupert-jung-mw]

Description

When generating a server interface with generatorName: kotlin-server, library: jaxrs-spec and interfaceOnly: true, the generated interface methods completely omit the operation summary/description from the OpenAPI spec. No KDoc/comment is produced at all for any operation.

That seems only be working for the generated models, but not for the generated API files.

For comparison, the plain Java generator with the equivalent jaxrs-spec library (JavaJaxRS/spec/apiInterface.mustache) does emit a Javadoc block with {{{notes}}} and @param, optionally combined with @ApiOperation/@Operation annotations via useSwaggerAnnotations/useSwaggerV3Annotations.

The Kotlin template kotlin-server/libraries/jaxrs-spec/apiInterface.mustache has no equivalent block at all — it only emits the JAX-RS annotations (@GET, @Path, etc.) with nothing for summary/notes.

openapi-generator version

7.24.0 (also reproducible on the templates shipped with recent 7.x releases)

OpenAPI declaration file content or url

Minimal reproducer:

    "/internal/v1/hello/hello-internal" : {
      "post" : {
        "tags" : [ "Hello" ],
        "summary" : "Say hello to given name",
        "operationId" : "helloInternal",
        "parameters" : [ {
          "name" : "name",
          "in" : "query",
          "description" : "Any name to return as greeting",
          "required" : true,
          "schema" : {
            "type" : "string"
          }
        } 

Suggested fix

The mustache template for kotlin-server could be corrected like this:

    {{#summary}}
    /**
     * {{{summary}}}
     {{#notes}}
     *
     * {{{notes}}}
     {{/notes}}
     {{#allParams}}
     {{#description}}
     * @param {{paramName}} {{{description}}}
     {{/description}}
     {{/allParams}}
     {{#returnType}}
     * @return {{{returnType}}}
     {{/returnType}}
     {{#isDeprecated}}
     * @deprecated
     {{/isDeprecated}}
     */
    {{/summary}}
    {{^summary}}
    {{#notes}}
    /**
     * {{{notes}}}
     {{#allParams}}
     {{#description}}
     * @param {{paramName}} {{{description}}}
     {{/description}}
     {{/allParams}}
     {{#returnType}}
     * @return {{{returnType}}}
     {{/returnType}}
     */
    {{/notes}}
    {{/summary}}
    {{#isDeprecated}}
    @Deprecated(message = "{{#notes}}{{{notes}}}{{/notes}}{{^notes}}deprecated{{/notes}}")
    {{/isDeprecated}}
    @{{httpMethod}}{{#subresourceOperation}}
    @Path("{{{path}}}"){{/subresourceOperation}}{{#hasConsumes}}
    @Consumes({{#consumes}}"{{{mediaType}}}"{{^-last}}, {{/-last}}{{/consumes}}){{/hasConsumes}}{{#hasProduces}}
    @Produces({{#produces}}"{{{mediaType}}}"{{^-last}}, {{/-last}}{{/produces}}){{/hasProduces}}
    {{#useCoroutines}}suspend {

I tested this template locally with the sample above and it works :)

Old output:

@POST @Produces("application/json", "text/plain") fun helloInternal(@QueryParam("name") @NotNull name: String): String

Output fix extended template:

/**
 * Say hello to given name
 *
 * @param name Any name to return as greeting
 * @return String
 */
@POST @Produces("application/json", "text/plain") fun helloInternal(@QueryParam("name") @NotNull name: String): String