KTOR-9165 and KTOR-9193 Documentation for OpenAPI specification generation #744

vnikolova · 2025-12-23T14:15:35Z

Add documentation for runtime route annotations
Update compiler plugin docs for new configuration options
add "what's new" sections
Add a sample project
Remove experimental label
update the Swagger UI and OpenAPI plugin topics

coderabbitai · 2025-12-23T14:15:41Z

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

…i compiler extension

codeSnippets/snippets/openapi-spec-gen/README.md

codeSnippets/snippets/openapi-spec-gen/build.gradle.kts

bjhham · 2026-01-12T09:53:43Z

codeSnippets/snippets/openapi-spec-gen/src/main/kotlin/com/example/Application.kt

+                }.annotate {
+                    summary = "Get users"
+                    description = "Retrieves a list of users."
+                    parameters {
+                        query("q") {
+                            description = "An encoded query"
+                            required = false
+                        }
+                    }
+                    responses {
+                        HttpStatusCode.OK {
+                            description = "A list of users"
+                            schema = jsonSchema<List<User>>()
+                        }
+                        HttpStatusCode.BadRequest {
+                            description = "Invalid query"
+                            ContentType.Text.Plain()
+                        }
+                    }
+                }


Would be good to leave a comment here that describes the order of precedence here in building the final model. In this case, we have the comment API and code inference that will supply some of the details, which will merged with the runtime API call from the annotate function.

Added a short paragraph below the example and a new section called "Metadata precedence". Not sure if the placement of it makes sense though and if it's better to place it higher up 🤔

bjhham · 2026-01-12T10:00:55Z

topics/openapi-spec-generation.md

+#### Supported KDoc fields
+
+| Tag             | Format                                          | Description                      |
+|-----------------|-------------------------------------------------|----------------------------------|
+| `@tag`          | `@tag *name`                                    | Groups the endpoint under a tag  |
+| `@path`         | `@path [Type] name description`                 | Path parameter                   |
+| `@query`        | `@query [Type] name description`                | Query parameter                  |
+| `@header`       | `@header [Type] name description`               | Header parameter                 |
+| `@cookie`       | `@cookie [Type] name description`               | Cookie parameter                 |
+| `@body`         | `@body contentType [Type] description`          | Request body                     |
+| `@response`     | `@response code contentType [Type] description` | Response definition              |
+| `@deprecated`   | `@deprecated reason`                            | Marks the endpoint as deprecated |
+| `@description`  | `@description text`                             | Extended description             |
+| `@security`     | `@security scheme`                              | Security requirements            |
+| `@externalDocs` | `@external href`                                | External documentation link      |


For 3.4.0, we're updating the comment API style from KDoc tags to use a custom markdown format, due to some concerns over the tags potentially causing some unexpected behaviour in the IDE and KDoc processing. I just changed this last week after some comments from @whyoleg, so it's pretty last-minute 😅

So now all these keywords instead just need to be at the start of the line with a colon divider to designate the value:

/** * Get a list of widgets. * * - Tags: * - widgets * - admin * - Cookie: X-Analytics-Session some tracking cookie * - Responses: * - 200 application/json [Widget]+ A list of widgets * - 400 Invalid request */

Note, the plural form with tags and responses is an optional format, you can also use Tag: widgets, and the list bullets at the top level are also optional and just a matter of preference for formatting.

Thanks for the tip. I've updated the section to reflect the changes.

bjhham · 2026-01-12T10:08:08Z

topics/openapi-spec-generation.md

+    val docs = generateOpenApiDoc(
+        OpenApiDoc(info = OpenApiInfo("My API", "1.0")),
+        apiRoute.descendants()
+    )
+    call.respond(docs)


Worth noting that docs is a io.ktor.openapi.OpenApiDoc and the return here is assuming you're using ContentNegotiation with kotlinx-serialization and JSON. Alternatively, you could just use Json.encodeToString(docs) with ContentType.Application.Json here with respondText so it's explicit in how it's serializing the model.

Added some clarification and a note with an alternative code sample using Json.encodeToString(docs) with ContentType.Application.Json.

bjhham · 2026-01-12T10:13:15Z

topics/openapi-spec-generation.md

+To expose the OpenAPI specification through an interactive UI, use the [OpenAPI](server-openapi.md)
+and [SwaggerUI](server-swagger-ui.md) plugins.


I'm not sure if we have good documentation for the difference between the two plugins. I don't really know the full extent of the differences, but from what I can tell the main difference is that the OpenAPI renders the HTML from the provided model on the back end, and SwaggerUI renders the details from the front end and exposes the model endpoint as JSON or YAML. I would say the Swagger plugin ought to be the default implementation since it's a more modern UI and it's easier to navigate. Maybe @e5l could have some thoughts on this.

Added a couple of bullet points to clarify the difference between the two and updated the plugin topics.

bjhham · 2026-01-12T10:16:39Z

topics/whats-new-340.md


+### Runtime route annotations
+
+Ktor 3.4.0 introduces the `ktor-server-routing-annotate` module, which allows you to attach OpenAPI metadata directly


I'm thinking of changing the name of this module before the release to ktor-server-openapi-annotate - I'd originally used routing because I was thinking of a more generic model and only providing the routing function in here, but since then it's become more OpenAPI-specific and provides the means for top-level information as well.

… rules

codeSnippets/build.gradle

topics/openapi-spec-generation.md

…id deps

vnikolova added 2 commits January 7, 2026 11:57

KTOR-9165 and KTOR-9193 docs for runtime route annotations and openap…

c3623a8

…i compiler extension

add a code sample project, update docs and add todos

ef10e78

vnikolova force-pushed the vnikolova/openapi-spec-gen branch from 3c9da2d to ef10e78 Compare January 7, 2026 10:58

vnikolova added 2 commits January 7, 2026 17:21

update openapi compiler plugin configuration

61898e8

update for technical accuracy and add links

a189f03

vnikolova marked this pull request as ready for review January 9, 2026 13:13

vnikolova changed the title ~~WIP: Documentation for OpenAPI specification generation~~ KTOR-9165 and KTOR-9193 Documentation for OpenAPI specification generation Jan 9, 2026

vnikolova requested a review from bjhham January 9, 2026 13:14

bjhham reviewed Jan 12, 2026

View reviewed changes

update comment formatting, add metadata precedence and code inference…

2422d37

… rules

bjhham reviewed Jan 12, 2026

View reviewed changes

codeSnippets/build.gradle Show resolved Hide resolved

topics/openapi-spec-generation.md Outdated Show resolved Hide resolved

update sample project, compiler config options descriptions and inval…

78a1528

…id deps

vnikolova force-pushed the vnikolova/openapi-spec-gen branch from c3130ed to 78a1528 Compare January 13, 2026 16:15

update the swagger and openapi plugin topics

320c30d

vnikolova force-pushed the vnikolova/openapi-spec-gen branch from 397e4a9 to 320c30d Compare January 14, 2026 10:37

vnikolova requested a review from nomisRev January 14, 2026 10:41

		To expose the OpenAPI specification through an interactive UI, use the [OpenAPI](server-openapi.md)
		and [SwaggerUI](server-swagger-ui.md) plugins.


		### Runtime route annotations

		Ktor 3.4.0 introduces the `ktor-server-routing-annotate` module, which allows you to attach OpenAPI metadata directly

KTOR-9165 and KTOR-9193 Documentation for OpenAPI specification generation #744

Are you sure you want to change the base?

KTOR-9165 and KTOR-9193 Documentation for OpenAPI specification generation #744

Uh oh!

Conversation

vnikolova commented Dec 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai bot commented Dec 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

vnikolova commented Dec 23, 2025 •

edited

Loading

coderabbitai bot commented Dec 23, 2025 •

edited

Loading