All jobs

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 RushOpens 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 with this body:

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

The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.

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

The same job on other stacks

Keep reading