What the agent does
The agent reads the routes and the types they encode before it writes a schema, because the document is only worth having if it matches what the server really returns. In an app generated from vapor/template, Package.swift declares swift-tools-version:6.3, depends on vapor from 4.121.4, fluent from 4.13.0 with a Fluent driver, swift-nio from 2.101.0, and turns on the ExistentialAny, InternalImportsByDefault and MemberImportVisibility upcoming features; the test target uses VaporTesting. Sources/App/routes.swift registers GET /, GET /hello and TodoController, whose boot adds GET /todos, POST /todos and DELETE /todos/:todoID. TodoDTO in Sources/App/DTOs/TodoDTO.swift is the wire type, with an optional id: UUID? and optional title, and Todo in Sources/App/Models/Todo.swift is the Fluent model behind it with a todos schema created by CreateTodo.
Three routes return three shapes: index returns [TodoDTO], create decodes a TodoDTO body and returns the saved one, and delete returns 204 or Abort(.notFound). The agent writes Sources/App/OpenAPI/OpenAPIDocument.swift, a Codable model of the OpenAPI 3.1 document built in code, not a hand-maintained YAML file, with one components.schemas.TodoDTO entry whose id is string with format: uuid and whose title is a nullable string, and one path item per route, including GET /hello with a text/plain response. The document is served by a small OpenAPIController at GET /openapi.json, and GET /docs returns a static HTML page that loads a documentation UI from a pinned CDN URL and points it at /openapi.json. Both are registered in routes.swift next to the existing collection.
The agent keeps the document honest with a test. Tests/AppTests/AppTests.swift already shows the pattern: a withApp helper that builds Application.make(.testing), runs configure, autoMigrate, the test body and autoRevert, and app.testing().test(.GET, "todos") with #expect assertions under Swift Testing. The new OpenAPITests suite fetches /openapi.json, decodes it, and asserts that every route Vapor reports in app.routes.all appears under paths with its method, so a route added later without a path item fails the suite. It also asserts the TodoDTO schema names exactly the two properties the DTO has, by decoding TodoDTO and comparing its coding keys.
The template's .github/workflows/test-template.yml runs swift test in a swift:6.3-noble container against MySQL, Postgres and SQLite, and builds the Docker image with docker compose build. The agent runs swift build and swift test in the sandbox with the SQLite variant, starts the app with swift run App serve and fetches /openapi.json and /docs with curl, and pastes the document and the test summary in the pull request.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add OpenAPI documentation to this Vapor app and open a pull request. Read Package.swift, Sources/App/routes.swift, Sources/App/configure.swift, Sources/App/entrypoint.swift, Sources/App/Controllers/TodoController.swift, Sources/App/DTOs/TodoDTO.swift, Sources/App/Models/Todo.swift, Sources/App/Migrations/CreateTodo.swift and Tests/AppTests/AppTests.swift first. Add Sources/App/OpenAPI/OpenAPIDocument.swift, a Codable OpenAPI 3.1 document built in code with a TodoDTO schema (id as a uuid string, title as a nullable string) and a path item for every route in routes.swift and TodoController, including the 204 and 404 responses of the delete route and the text/plain response of GET /hello. Add an OpenAPIController serving GET /openapi.json and GET /docs, the latter an HTML page loading a documentation UI from a pinned CDN URL and pointing it at /openapi.json, and register it in routes.swift. Add an OpenAPITests suite in Tests/AppTests using the existing withApp helper that decodes /openapi.json and asserts every route in app.routes.all has a matching path and method, and that the TodoDTO schema lists exactly the DTO's coding keys. Run swift build and swift test, start the server, curl /openapi.json and /docs, and paste the document and the test summary in the pull request. Do not change the existing routes, DTOs or migrations.",
"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 with Sources/App/OpenAPI/OpenAPIDocument.swift, Sources/App/Controllers/OpenAPIController.swift, two registrations in routes.swift and a new suite in Tests/AppTests. The description includes the served /openapi.json, so a reviewer reads the five path items and the TodoDTO schema without checking the branch out, plus the swift test summary.
The template's workflow runs swift test against each database and builds the container on every pull request, so a compile error under the strict upcoming features or a document that misses a route fails there. Nothing else in CI reads the document, so the pasted JSON is the evidence for its content.
A reviewer checks that the TodoDTO schema matches the optionals in the DTO, that DELETE /todos/{todoID} documents both 204 and 404, that the docs page loads its UI from a pinned version and not latest, and that /openapi.json is reachable without a database so a docs portal can fetch it during a migration. Then they publish the URL to the team that consumes the API.
Run it on every new API service
A team that wants every Vapor service to publish its own OpenAPI document sends one POST /o/{org}/sessions per repository with this prompt and that repository in resources. Each run reads its own route collections and DTOs, so a service with ten controllers gets ten groups of path items and a schema per Content type, and each opens its own pull request on its own branch.
Send a request_id with each body so a retry returns the run already started. With a webhook_url on the API key, Rush POSTs run.completed when each turn ends, with the session_url to read the pull request from, so the API catalog can be updated as each one merges.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
API documentation drifts because it is written once and the code moves on. The agent writes the document from the routes and DTOs as they are, and adds the test that compares app.routes.all to paths, so the next route without a path item fails swift test. In a Rush sandbox it compiles the Swift 6.3 package with the template's strict settings, runs the suite and serves the document, and every command and response is kept in the run's record.
The result is a URL, not a promise: the pull request shows the /openapi.json the running server returned. The same request body works unchanged on any Vapor service a team runs, and runs for several repositories proceed at once, each in its own sandbox with its own Swift toolchain and database.
Frequently asked questions
Why build the document in Swift instead of writing YAML?
Because the test can then compare the document to app.routes.all and to TodoDTO's coding keys at test time, which a static file cannot do. It also keeps one source: the path for DELETE /todos/:todoID comes from the same string TodoController.boot registers.
Does it depend on a code-generation tool?
No. The template compiles under swift-tools-version:6.3 with several upcoming features enabled, and adding a generator plugin to that build is a larger decision than documenting three routes. The pull request adds no package dependency; if the team later adopts a generator, the test still guards the output.
Does the docs page work offline?
/openapi.json is served by the app and needs nothing external. /docs is a static HTML page that loads its UI from a pinned CDN URL, so it needs the browser to reach that CDN; a team that wants it self-hosted vendors the assets into Public/ and enables FileMiddleware, which configure.swift leaves commented out.
Will the test suite still pass with Fluent on Postgres?
Yes. The new suite uses the same withApp helper as AppTests, so it migrates and reverts against whichever database the DATABASE_HOST environment points at, as test-template.yml does for MySQL, Postgres and SQLite. The document itself does not touch the database.