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

[vivekkumarq]

Fixes #24794.

The kotlin-server jaxrs-spec apiInterface.mustache template emitted only the JAX-RS annotations, so an interfaceOnly: true API interface carried no documentation for its operations at all. The equivalent Java template (JavaJaxRS/spec/apiInterface.mustache) has always emitted a Javadoc block, and the models generated by this same library already carry KDoc, so the API interfaces were the odd ones out.

Change

A KDoc block built from the operation summary and notes, with @param for documented parameters and @return listing the responses.

Two details worth flagging for review:

• The @return formatting follows the kotlin-server javalin6 templates (successful operation (status code 200) / or ...) rather than the Java template's {{#responses}}@return {{{message}}}{{/responses}}, which emits one @return line per response. This keeps the output consistent within the Kotlin generator and valid as KDoc.
• The block is omitted entirely when an operation has neither a summary nor notes, so operations without documentation do not gain an empty /** */. The Java template emits its block unconditionally.

@param is only emitted for parameters that actually have a description, so undocumented parameters do not produce a bare @param name line.

Generated output

Before:

    @GET
    @Path("/findByStatus")
    @Produces("application/xml", "application/json")
    fun findPetsByStatus(@QueryParam("status") status: kotlin.collections.List<kotlin.String>): io.smallrye.mutiny.Uni<Response>

After:

    /**
     * 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>

Samples

Regenerated with ./bin/generate-samples.sh for the four kotlin-server-jaxrs-spec* configs. Only the two that set interfaceOnly produce output changes, since the others generate through apiMethod.mustache:

• samples/server/others/kotlin-server/jaxrs-spec-array-response
• samples/server/petstore/kotlin-server/jaxrs-spec-mutiny

Note

apiMethod.mustache in the same library has the same gap for the non-interfaceOnly case. I left it out to keep this change scoped to the reported issue — happy to follow up separately, or fold it in here if you would prefer.

PR checklist

• Read the contribution guidelines.
• Ran the build and regenerated the affected samples, and committed the changed files.
• @jimschubert as the Kotlin technical committee member.

---

Summary by cubic

Fixes #24794 by emitting KDoc on operation methods in kotlin-server jaxrs-spec interfaces when interfaceOnly is set, so generated API docs match the Java generator and model KDoc. Previously these interfaces had no method documentation.

• Builds KDoc from operation summary/notes, @param for described parameters, and @return listing responses.
• Omits the block when an operation has no summary or notes.
• Regenerated the two affected samples; apiMethod.mustache is out of scope.

^{Written for commit 0a85fbb. Summary will update on new commits.}

[cubic-dev-ai]

1 issue found across 5 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="modules/openapi-generator/src/main/resources/kotlin-server/libraries/jaxrs-spec/apiInterface.mustache">

<violation number="1" location="modules/openapi-generator/src/main/resources/kotlin-server/libraries/jaxrs-spec/apiInterface.mustache:14">
P3: In the new @return block, {{message}} uses double-stache, which HTML-escapes the value, while summary, notes, and @param descriptions in this same change use triple-stache {{{...}}} and the Java template renders messages with {{{message}}}. A response message containing &, <, or > will be emitted literally as &amp;, &lt;, etc. in the generated KDoc. Use {{{message}}} for consistency and correct output. (By default the Mustache renderer escapes {{ }} content.)</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P3: In the new @return block, {{message}} uses double-stache, which HTML-escapes the value, while summary, notes, and @PARAM descriptions in this same change use triple-stache {{{...}}} and the Java template renders messages with {{{message}}}. A response message containing &, <, or > will be emitted literally as &, <, etc. in the generated KDoc. Use {{{message}}} for consistency and correct output. (By default the Mustache renderer escapes {{ }} content.)

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At modules/openapi-generator/src/main/resources/kotlin-server/libraries/jaxrs-spec/apiInterface.mustache, line 14:

<comment>In the new @return block, {{message}} uses double-stache, which HTML-escapes the value, while summary, notes, and @param descriptions in this same change use triple-stache {{{...}}} and the Java template renders messages with {{{message}}}. A response message containing &, <, or > will be emitted literally as &amp;, &lt;, etc. in the generated KDoc. Use {{{message}}} for consistency and correct output. (By default the Mustache renderer escapes {{ }} content.)</comment>

<file context>
@@ -1,3 +1,43 @@
+    {{/description}}
+    {{/allParams}}
+    {{#responses.0}}
+     * @return {{#responses}}{{message}} (status code {{code}}){{^-last}}
+     *         or {{/-last}}{{/responses}}
+    {{/responses.0}}
</file context>

Suggested change

	* @return {{#responses}}{{message}} (status code {{code}}){{^-last}}
	* @return {{#responses}}{{{message}}} (status code {{code}}){{^-last}}

[vivekkumarq]

Thanks — all three were fair, and the first one was a real bug. Fixed in the amended commit.

@param file referenced a parameter that does not exist. Correct, and it matters here more than usual since the point of the change is accurate documentation. formParams.mustache renders file form parameters as {{paramName}}InputStream, so the generated method takes fileInputStream while the KDoc said file. The @param name is now built the same way formParams.mustache builds it, scoped to form file parameters only:

 * @param {{paramName}}{{#isFormParam}}{{#isFile}}InputStream{{/isFile}}{{/isFormParam}} {{{description}}}

samples/.../jaxrs-spec-mutiny/.../PetApi.kt now reads @param fileInputStream file to upload.

{{message}} escaping. Agreed, and it was inconsistent with the summary, notes and @param descriptions in the same block. Now {{{message}}}, matching the Java template.

Duplicated body across the two branches. Agreed. The shared portion now lives in a new operationDoc.mustache partial that both branches include, so @param, @return and @deprecated handling exists once.

One implementation note on the partial, in case it comes up: the partial has to carry its own indentation with the {{>operationDoc}} tag at column zero. Indenting the tag causes the renderer to add the tag's indentation to every line of the partial and to compound it across the nested sections, which produced output like this:

    /**
     * uploads an image
         * @param petId ID of pet to update
             * @return successful operation (status code 200)

Samples regenerated. Apart from the @param fileInputStream line the generated output is byte-identical to the previous commit, so the partial extraction and the escaping change are behaviour-preserving.