Hi Team, I am using the following environment for ...

# ktor

[Sangeeta]

Hi Team,
I am using the following environment for my project:
• Kotlin: 2.2.20
• Ktor: 3.3.1
I am generating OpenAPI specifications using ./gradlew buildOpenApi. I noticed a couple of things:
1. The @description annotation in KDoc (as documented here) does not appear in the generated OpenAPI output. It seems the description is ignored, while the first line of the KDoc becomes the summary.
2. The OpenAPI spec currently includes internal endpoints (e.g., /json/kotlinx-serialization). Is there a way/annotation to exclude such endpoints from the generated spec?
3. Is there any support or recommended approach for nested tags? Currently, only flat tag grouping is supported.
Thanks in advance for the guidance!

[Bruce Hamilton]

Hey, thanks for the feedback!

1. This looks like a bug - there's no way to include the description atm. Should be an easy fix for the next release.
2. Yes, you can prefix these with // @ignore. Sorry if this is missing from the docs. We should provide an opt-in mechanism for the full release too.
3. Do you mean the inclusion of an @tag for all sub-routes? This should be working, perhaps there's an issue there.

[Sangeeta]

Thanks for the quick response, Bruce!
1. Good to know the KDoc description issue is a bug — will look forward to the fix.
2. // @ignore works for us for now — thanks for confirming!
3. From the nested tags, I meant support for https://www.openapis.org/blog/2025/09/23/announcing-openapi-v3-2
One of the most significant changes, particularly for rendering a graphical view of an OpenAPI description, is the change to the Tags object. The new Tag Object structure introduces *summary* for short descriptions, *parent* for nesting, and *kind* for classifying Tags, allow a taxonomy to be developed, supported by a registry of commonly supported values.

[Bruce Hamilton]

Ohh no, we're just working with the 3.1 schema for now. I'll make a note of potentially supporting OpenAPI 3.2 in Ktor 3.4 🤞

[Sangeeta]

Thank you 🙂

[Sangeeta]

@Bruce Hamilton I have one more query — how can we enable model field descriptions in the generated OpenAPI documentation?
For example, I’m using @Serializable models like this:

@Serializable
data class Book(
    @Schema(description = "Unique ID of the book")
    val id: String,
    @Schema(description = "Title of the book")
    val title: String,
    @Schema(description = "Author name")
    val author: String,
    @Schema(description = "Year of publication")
    val year: Int
)

The OpenAPI spec is generated fine, but the field-level description values from @Schema are not showing up in the output.
Is there any configuration or plugin support needed to make these appear in the generated OpenAPI file when using @Serializable data classes?

[Bruce Hamilton]

Oh, that would be useful, I haven't yet accounted for schema annotations like this. Is this a library you're using here?

[Sangeeta]

Yes, I am using io.swagger.core.v3:swagger-annotations. Is there a way to include or generate model field descriptions from these annotations, or through any other approach, in the generated OpenAPI documentation?

[Bruce Hamilton]

Nope, nothing yet I'm afraid 😞
I'll look into the swagger annotations for 3.4 though