# Add OpenAPI Docs to a Ktor Server

Yes. An agent documents each Ktor route with KDoc, turns on the Ktor Gradle plugin's OpenAPI generation, serves the spec at /docs, tests it and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-openapi-docs/ktor/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads the build and the routes before writing a line of documentation. In a server shaped like the `postgres` sample in ktorio/ktor-samples, `build.gradle.kts` applies `kotlin("jvm")` 2.4.20, `io.ktor.plugin` 3.6.0 and the kotlinx serialization plugin, depends on `ktor-server-core-jvm`, `ktor-server-content-negotiation-jvm`, `ktor-serialization-kotlinx-json-jvm`, `ktor-server-netty-jvm`, `ktor-server-config-yaml` and `org.postgresql:postgresql` 42.7.8, and has `ktor-server-test-host-jvm` and `kotlin-test-junit` for tests, on a JVM 17 toolchain. `application.yaml` loads `com.example.PostgresApplicationKt.module` on port 8080. `PostgresApplication.kt` calls `configureSerialization()` and `configureRouting(connectToPostgres(embedded = false))`, and `plugins/Routing.kt` defines `POST /articles` answering `201` with the new id, `GET /articles/{id}` answering `200`, `404` or `400`, and `PUT` and `DELETE` on the same path, all over the `Article(title, body)` data class from `models/Article.kt`. There is no `src/test` directory and nothing describes the API to a client.

The same repository shows the pattern to copy. The `openapi` sample's `build.gradle.kts` has a `ktor { openApi { title, version, summary } }` block and a `ktor-server-openapi` dependency, its routes carry KDoc comments such as `@response 200 text/plaintext Hello`, and `OpenApi.kt` serves the generated file with `openAPI(path = "/docs", swaggerFile = "openapi/generated.json")`. The agent brings that into the `postgres` sample: the `openApi` block with a title and version taken from the project's `group` and `version`, the `io.ktor:ktor-server-openapi` dependency in the same coordinate style the file already uses, and KDoc on each of the four routes in `Routing.kt` naming the `Article` request body, the `id` path parameter and every status the handler can answer, including the `500` the `POST` handler returns on `DbElementInsertException`.

A new `plugins/OpenApi.kt` adds `configureOpenApi()` with the `/docs` route, and `PostgresApplication.kt` calls it before `configureRouting`. Because the module opens a JDBC connection at startup from `postgres.yaml`, the agent keeps that call where it is and writes the test so it never runs: `src/test/kotlin/OpenApiTest.kt` uses `testApplication` from the test host with an `application { configureSerialization(); configureOpenApi() }` block, requests `/docs`, asserts `200`, and asserts the body is JSON whose `paths` contain `/articles` and `/articles/{id}` with the four methods.

Then it proves the generated file matches the routes. It runs `./gradlew build` in the sample, reads `openapi/generated.json` from the build output, and checks each path and status against `Routing.kt` by hand, fixing any KDoc tag the generator ignored. It starts Postgres from the sample's `docker-compose.yaml`, runs `./gradlew run`, fetches `/docs` with `curl`, and pastes the paths section into the pull request alongside the `README.md` lines it adds about where the documentation is served.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add OpenAPI documentation to the Ktor server in the postgres sample and open a pull request. Read postgres/build.gradle.kts, postgres/gradle.properties, postgres/src/main/resources/application.yaml, postgres/src/main/kotlin/com/example/PostgresApplication.kt, plugins/Routing.kt, models/Article.kt, service/ArticleService.kt and postgres/README.md, and the openapi sample's build.gradle.kts, OpenApi.kt and Routing.kt for the pattern. In the postgres sample add the ktor openApi block to build.gradle.kts with a title and version, add the io.ktor:ktor-server-openapi dependency in the same coordinate style the file uses, and write KDoc on each route in Routing.kt naming the Article body, the id parameter and every status the handler returns. Add plugins/OpenApi.kt with configureOpenApi() serving openapi/generated.json at /docs and call it from the module before configureRouting. Add src/test/kotlin/OpenApiTest.kt using testApplication with only configureSerialization and configureOpenApi so it needs no database, asserting /docs answers 200 with paths for /articles and /articles/{id} and their methods. Run ./gradlew build and ./gradlew test, compare the generated paths with Routing.kt, start Postgres from docker-compose.yaml, run the app and include the curl output for /docs in the pull request. Add a README line on where the docs are served. Do not change the handlers' behaviour.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request that changes `postgres/build.gradle.kts`, `Routing.kt`, `PostgresApplication.kt` and `README.md`, and adds `plugins/OpenApi.kt` and `src/test/kotlin/OpenApiTest.kt`. The description shows the `gradlew test` result, the `paths` section of the generated document as `curl` returned it from `/docs`, and a short table matching each route's statuses in `Routing.kt` to the responses in the document.

On a repository with the samples' `build-all.yml` workflow, the pull request runs `build-all.sh`, which builds each sample in turn, so the new dependency and test are compiled on the pull request itself. The `detekt-analysis.yml` workflow reads the Kotlin sources, and KDoc comments give it nothing new to flag.

A reviewer checks that every status in the document is one the handler can return, that the `Article` schema in the generated file has `title` and `body` as required strings, and that `/docs` is a path they are happy to expose, since nothing in the sample authenticates requests. Then they decide whether to add Swagger UI, which the pull request leaves out.

## Run it on every new Ktor service

Send one `POST /o/{org}/sessions` per Ktor repository with this prompt and that repository in `resources`. Each run reads its own `build.gradle.kts` and routing files, so a service on an older Ktor plugin without the OpenAPI extension gets a hand-written `openapi/documentation.yaml` served by the same plugin instead, and a service that already serves `/docs` gets its KDoc brought up to date with the routes.

Give the API key a `webhook_url` and Rush POSTs `run.completed` when each turn finishes, with the `session_url` to read the pull request link from, so a handler on your server can post it where that service's owners review.

## Why run it on Rush?

Generated documentation is only as true as the comments it is built from, and the check is to build, read the output, and compare it with the handlers. The agent does that in its sandbox, with the Gradle build, the Postgres container from `docker-compose.yaml` and the running server, and every command and its output stays in the run's record, so the pull request shows the document a client would download rather than the comments that should produce it.

A Ktor build with the Gradle plugin and a JVM 17 toolchain takes long enough that a laptop is tied up while it runs, and a first `./gradlew build` on a fresh checkout downloads a lot. In Rush that happens in the run's own sandbox, and the same request body documents every Ktor service a team owns, each in its own run.

## Frequently asked questions

### Does the generated document include the Article schema?

Yes. The `Article` data class is annotated `@Serializable`, and the KDoc on `POST /articles` and `PUT /articles/{id}` names it as the request body, so the generator emits a schema with `title` and `body`. The test checks the paths; the reviewer reads the schema in the pasted output.

### Why does the test skip the database?

The module opens a JDBC connection from `postgres.yaml` at startup, which would make the test depend on a running Postgres. `testApplication` with only `configureSerialization` and `configureOpenApi` boots the route under test and nothing else, so `./gradlew test` passes on any machine.

### Can it serve Swagger UI as well?

Ktor has a separate `ktor-server-swagger` plugin that renders the same file. The pull request serves the document only, because that is what a client or a generator needs; ask for Swagger UI in `input` and the agent adds the dependency and a second route.

### Will the KDoc comments drift from the code?

They live on the route they describe, and the test fails if a documented path disappears from the generated file. For the statuses, the pull request's table is the reviewer's check; a follow-up run can be asked to compare them again after a routing change.

## More Ktor jobs

- [Add OpenTelemetry Tracing to a Ktor Server](https://getrush.ai/run/add-opentelemetry/ktor/)
- [Add Prometheus Metrics to a Ktor Server](https://getrush.ai/run/add-prometheus-metrics/ktor/)
- [Add Rate Limiting to a Ktor API](https://getrush.ai/run/add-rate-limiting/ktor/)

## The same job on other stacks

- [Add OpenAPI Docs to a Rocket API](https://getrush.ai/run/add-openapi-docs/rocket/)
- [Add OpenAPI Docs to a Slim 4 App](https://getrush.ai/run/add-openapi-docs/slim/)
- [Generate an API Reference From an OpenAPI Spec in a Starlight Site](https://getrush.ai/run/add-openapi-docs/starlight/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
