# Add OpenAPI Docs to a Vapor API

Yes. An agent adds a served OpenAPI 3 document and a docs page to your Vapor app, describes every route from the code, tests the document, and opens a PR.

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

## 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`

```json
{
  "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"
    }
  ]
}
```

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 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.

## 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.

## More Vapor jobs

- [Add Prometheus Metrics to a Vapor App](https://getrush.ai/run/add-prometheus-metrics/vapor/)
- [Add Rate Limiting to a Vapor App](https://getrush.ai/run/add-rate-limiting/vapor/)
- [Add Request ID Logging to a Vapor App](https://getrush.ai/run/add-request-id-logging/vapor/)

## The same job on other stacks

- [Add OpenAPI Docs to an Actix Web API](https://getrush.ai/run/add-openapi-docs/actix/)
- [Add OpenAPI Docs to an Axum API from a Linear Issue](https://getrush.ai/run/add-openapi-docs/axum/)
- [Add OpenAPI Docs to a chi API](https://getrush.ai/run/add-openapi-docs/chi/)

## 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/)
