# Add OpenAPI Docs to an Axum API from a Linear Issue

Yes. An agent derives OpenAPI schemas with utoipa on every handler and type, serves the document from a route, checks it against the real server, and opens a PR.

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

## What the agent does

The agent reads the API before it documents it. In a service shaped like launchbadge/realworld-axum-sqlx, `Cargo.toml` pins `axum` at 0.3.4, `sqlx` 0.5 with Postgres, `tokio` 1.14, `tower-http` 0.2 for the trace layer, `clap` 3 for `Config`, `jwt` 0.15 and `serde`. `src/http/mod.rs` merges three routers in `api_router()` and binds `0.0.0.0:8080` in `serve`; `users.rs` registers `POST /api/users`, `POST /api/users/login` and `GET` plus `PUT /api/user`; `profiles.rs` registers `/api/profiles/:username` and its follow routes; `articles/mod.rs` registers the article routes, `/api/articles/feed` and `/api/tags`, and `articles/comments.rs` the comment routes. `extractor.rs` reads `Authorization: Token <jwt>` for `AuthUser`, and `error.rs` maps the `Error` enum to 401, 403, 404 and 422.

The types are already serde structs with names worth keeping: `UserBody<T>`, `NewUser`, `LoginUser`, `UpdateUser` and `User` in `users.rs`, `ListArticlesQuery` with `tag`, `author`, `favorited`, `limit` and `offset` in `articles/listing.rs`, and `MultipleArticlesBody` for the list response. The agent adds `utoipa` to `Cargo.toml`, derives `ToSchema` on each of them, and puts a `#[utoipa::path]` attribute on every handler with its method, path, query or body type, the responses the handler can return and the `Token` security requirement on the routes that take `AuthUser`. One `ApiDoc` struct with `#[derive(OpenApi)]` lists the paths and components and declares the `Token` scheme as an API key in the `Authorization` header.

The document is served from a route in the same style as the others: a handler that returns `Json(ApiDoc::openapi())` at `GET /api/openapi.json`, merged into `api_router()`. The agent does not add a Swagger UI, because the `utoipa-swagger-ui` crate's `axum` feature depends on axum ^0.8.4 and this service is on 0.3, and says so in the description rather than pulling the service through a framework upgrade it was not asked for.

Checking it needs a database, because the `sqlx::query!` macros check their SQL at compile time against `DATABASE_URL`, which is why `.github/workflows/rust.yml` starts a Postgres service and runs `sqlx db setup` before `cargo build`. The agent does the same in its sandbox: start Postgres, set `DATABASE_URL` and `HMAC_KEY` as `.env.sample` describes, `cargo install sqlx-cli`, `sqlx db setup`, then `cargo build` and `cargo test`. It starts the server, fetches `/api/openapi.json`, lints it with an OpenAPI validator, and compares every `.route(` in `src/http` against the document's paths so no handler is left out.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "A Linear issue labelled agent asks for an OpenAPI 3 document for this API, served from the API itself, with every route, its request and response bodies, query parameters, the Token authorization scheme and the error statuses. Read Cargo.toml, src/http/mod.rs, src/http/users.rs, src/http/profiles.rs, src/http/articles/mod.rs, src/http/articles/listing.rs, src/http/articles/comments.rs, src/http/extractor.rs, src/http/error.rs, .env.sample and .github/workflows/rust.yml first. Add utoipa, derive ToSchema on the request and response types, annotate every handler with utoipa::path including the Token security requirement where AuthUser is extracted, build an ApiDoc with the paths, components and security scheme, and serve it as JSON from GET /api/openapi.json. Do not upgrade axum. Start Postgres in the sandbox, set DATABASE_URL and HMAC_KEY, run sqlx db setup, cargo build and cargo test, start the server, fetch the document, validate it with an OpenAPI linter, and check that every .route( in src/http appears in it. Open a pull request that links the issue and lists the documented paths.",
  "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 on its own branch. `Cargo.toml` and `Cargo.lock` gain `utoipa`; `src/http/users.rs`, `profiles.rs`, `articles/mod.rs`, `articles/listing.rs` and `articles/comments.rs` gain `ToSchema` derives and a `#[utoipa::path]` block above each handler; `src/http/mod.rs` gains the `ApiDoc` struct and the `/api/openapi.json` route. No handler body changes, and no route moves. The description lists every documented path with its method, names the security scheme, and quotes the issue.

The checks are the proof. The repository's `Rust` workflow runs on the pull request, builds against its Postgres service, runs `cargo test` and then the Realworld Postman collection against the server on port 8080, so a change that broke a handler shows there. The trajectory at `GET /o/{org}/sessions/{id}/messages` keeps the `sqlx db setup`, `cargo build` and `cargo test` output, the fetched document, the linter's result and the route-by-route comparison, so a reviewer reads what the document contains rather than trusting a description.

Before merging, a reviewer reads the generated JSON for the response shapes of the routes they care about, checks that the 401 and 422 responses match what `error.rs` produces, and decides whether the document should be public or behind the same `Token` check as the rest of the API. Nothing is deployed until the pull request merges.

## Run it on every Linear issue labelled agent

Sign in to Linear once from Settings → Connections, then add an automation to the Project that holds the API with this prompt and a `linear` trigger on `linear.issue.labeled`, with the label in `config.labels`. The trigger adds the labelled issue after the prompt and fills in no placeholder, so the agent reads what the issue asks for, a document only or a document plus examples, from the issue text. Each labelled issue starts its own run in its own sandbox and ends in its own pull request, up to the automation's `max_runs_per_hour`.

From your own server instead, a handler that receives Linear's webhook for the label sends `POST /o/{org}/sessions` with the repository and `https://linear.app/<workspace>/issue/<ID>` in `resources`, so the issue reaches the prompt through your Linear connection, and a `request_id` that is a UUID v5 of the issue id so a redelivered webhook returns the run it already started. A `webhook_url` on that key receives `run.completed` or `run.failed` with `data.session_url` to read for the pull request link.

## Why run it on Rush?

Documenting an axum service is an edit-compile-fetch loop, and on this one the compile step needs a live Postgres for the `sqlx::query!` macros before `cargo build` will even start. On a laptop that means a database container, the right `DATABASE_URL`, `sqlx db setup`, and a cargo build that competes with everything else for the CPU. In a Rush sandbox the agent sets all of that up once, builds, runs the server, fetches the document and fixes the annotations until the linter and the route comparison are clean, and your machine does none of it.

The pull request carries its proof: the repository's own workflow builds and runs the Postman collection against the changed server, and the transcript keeps the fetched document and the linter output beside the commands that produced them. A second issue, for examples on every schema or for a Redoc page, is a second sandbox and a second pull request at the same time.

## Frequently asked questions

### Why is there no Swagger UI page?

Because the `utoipa-swagger-ui` crate's `axum` feature depends on axum ^0.8.4 and this service pins 0.3.4. Pulling the UI in would mean upgrading axum, which touches every extractor and the server bootstrap, and the issue did not ask for that. The agent serves the JSON document and says so in the pull request; any Swagger UI or Redoc instance can load it from `/api/openapi.json`.

### Does it change any handler?

No. `#[utoipa::path]` is an attribute above each handler and `ToSchema` is a derive on the existing structs; the function bodies and the `Router` calls stay as they are. The one new piece of code is the handler that returns `Json(ApiDoc::openapi())` and its route in `api_router()`. `cargo test` and the Postman collection in CI show the behaviour is unchanged.

### How does it know the document is complete?

It compares the routes and the document mechanically: every `.route(` call in `src/http` is listed with its method and path and checked against the paths in the fetched JSON, and the result is in the trajectory. A missing handler fails that comparison before the pull request opens. The OpenAPI linter catches the other class of mistake, a schema that references a component that was never registered in `ApiDoc`.

### Why does the build need a database?

The service uses `sqlx::query!` macros, which check each SQL statement against a live schema at compile time through `DATABASE_URL`, and the repository ships no offline query data. `.github/workflows/rust.yml` starts a Postgres service and runs `sqlx db setup` for the same reason. The agent starts Postgres in its own sandbox and follows the workflow's steps; the database never leaves the sandbox.

### Will the document show the Token scheme on the right routes?

Yes. The agent marks a route as requiring `Token` when its handler takes the `AuthUser` extractor, and leaves it open when it takes `MaybeAuthUser` or nothing, which is how `extractor.rs` distinguishes them. The scheme itself is declared once in `ApiDoc` as an API key in the `Authorization` header with the `Token` prefix the extractor expects.

## More Axum jobs

- [Add Prometheus Metrics to an Axum API](https://getrush.ai/run/add-prometheus-metrics/axum/)
- [Add Rate Limiting to an Axum API](https://getrush.ai/run/add-rate-limiting/axum/)
- [Add Refresh Tokens to an Axum JWT API](https://getrush.ai/run/add-refresh-tokens/axum/)

## The same job on other stacks

- [Add OpenAPI Docs to a chi API](https://getrush.ai/run/add-openapi-docs/chi/)
- [Add OpenAPI Docs to a Django REST Framework API](https://getrush.ai/run/add-openapi-docs/django-rest-framework/)
- [Serve OpenAPI Docs from a Fastify API from a Linear Issue](https://getrush.ai/run/add-openapi-docs/fastify/)

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