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 with this body:
{
"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"
}
]
}- 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.
- 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.
- 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.
The use case this job follows, with its automation and trigger: Hand off a long task.
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.