All jobs

Add OpenAPI Docs to a Hono API

Yes. An agent moves your Hono routes onto @hono/zod-openapi with typed schemas, serves the document and Swagger UI, keeps every status code, 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 routes and the tests that pin them before it touches a schema. In the blog example of honojs/examples, a Cloudflare Worker on hono ^4.2.4 with a KV namespace bound as BLOG_EXAMPLE, src/api.ts builds a Hono<{ Bindings }> with cors() on /posts/* and five handlers: GET /posts lists, POST /posts answers 201 or 422 when model.createPost refuses a body without title and body, GET /posts/:id answers 404, and PUT and DELETE /posts/:id answer 204 with no body when the post is missing and { ok } otherwise. src/index.ts mounts a middleware app with prettyJSON and basicAuth on non-GET /posts/* requests, then mounts api under /api. src/model.ts holds the Post and Param types and the KV reads and writes. src/api.test.ts drives all five routes through worker.request with env from cloudflare:test, and package.json runs it with vitest --run on @cloudflare/vitest-pool-workers.

It adds @hono/zod-openapi, zod and @hono/swagger-ui. The current @hono/zod-openapi lists hono >= 4.10.0 and zod 4 as peers, and the example's caret range resolves to a current 4.x on install, which the agent confirms from node_modules/hono/package.json before going further. src/api.ts becomes an OpenAPIHono<{ Bindings }>; the Post and Param types in src/model.ts get PostSchema and ParamSchema beside them with .openapi() names, and each handler is declared with createRoute, its request params or JSON body and its responses by status, including the 204, 404 and 422 cases, so the document describes what the code does today rather than a cleaner API it does not have.

The contract is kept on purpose. Zod validation would turn a body without title into a 400 by default, which the current code answers 422, so the agent sets a defaultHook on the OpenAPIHono that answers 422 with the same { error, ok: false } shape. GET /doc serves the document with api.doc and GET /ui serves swaggerUI({ url: '/api/doc' }); because src/index.ts mounts the app under /api, their full paths are /api/doc and /api/ui, both GET, so the basic auth on writes never applies to them. The cors() call and the basicAuth middleware in index.ts are untouched.

src/api.test.ts runs unchanged, which is the point: the same requests get the same statuses and bodies. One test is added at the end that fetches /doc, parses it, and asserts that paths lists /posts and /posts/{id} with the five operations and that the POST /posts request body references the Param schema. The agent runs npm test with a wrangler.toml made from wrangler.example.toml, as the vitest config requires, and npx tsc --noEmit against the example's tsconfig.json, then updates the endpoint list in README.md with the two new routes.

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 Hono API in this repository and open a pull request. Read package.json, wrangler.example.toml, vitest.config.ts, tsconfig.json, src/index.ts, src/api.ts, src/model.ts, src/bindings.ts, src/api.test.ts and README.md first. Install @hono/zod-openapi, zod and @hono/swagger-ui, and confirm the installed hono version satisfies the zod-openapi peer range. Change src/api.ts to an OpenAPIHono with the same Bindings type, add PostSchema and ParamSchema with .openapi() names next to the types in src/model.ts, and declare every existing route with createRoute, documenting the real responses: 200 and 201 bodies, the 404 on GET by id, the 422 on POST with a missing title or body, and the 204 with no body that PUT and DELETE return when the post does not exist. Set a defaultHook so a body that fails validation still answers 422 with { error, ok: false } as the code does now. Serve the document at GET /doc and Swagger UI at GET /ui pointing at /api/doc. Keep cors and the basicAuth middleware in src/index.ts unchanged. src/api.test.ts must pass without edits; add one test that fetches /doc and asserts the five operations and the Param request body. Copy wrangler.example.toml to wrangler.toml for the test run, run npm test and npx tsc --noEmit, paste the output in the pull request description, and add the two routes to the endpoint list in README.md.",
  "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 that rewrites src/api.ts on OpenAPIHono, adds two schemas to src/model.ts, adds three packages to package.json and the lockfile, appends one test to src/api.test.ts, and updates README.md. The description shows the vitest --run output with the existing tests still passing, the tsc output, and the paths section of the generated document as fetched from the running worker.

The agent pushes one commit for the schemas and routes, one for the document and UI routes, and one for the test and README. A reviewer opens /api/ui from wrangler dev, tries POST /posts with an empty body from the UI, and sees the same 422 the old code gave.

A reviewer checks that no status code moved, that the 204 responses are documented with no content rather than invented bodies, that the document and UI are reachable without the basic auth credentials, and that the generated schema names match the types in src/model.ts. Then they merge and point API consumers at /api/doc.

Run it on every new Hono service

A team with several Workers starts one run per repository with POST /o/{org}/sessions, this prompt and the repository in resources. The agent reads each service's own routes and tests, so a service that already validates with hono/validator gets its schemas reused rather than duplicated, and each run opens its own pull request.

The key's webhook_url receives run.completed for each run with a session_url, so a script can post the pull request links and the /doc URLs to the team channel as they land.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

Writing an OpenAPI document by hand drifts from the code within weeks; deriving it from the route definitions keeps the two together, but the move changes how bodies are validated and can quietly change status codes. In a Rush sandbox the agent runs the existing test file after every edit and fetches the generated document from the worker, and that output is kept in the transcript, so the pull request shows the contract was kept rather than promising it.

The result follows the example's own layout, types in model.ts, routes in api.ts, tests in api.test.ts, and passes vitest on the Workers pool and tsc before a reviewer opens it. The same request works unchanged across every Hono service the team owns.

Frequently asked questions

Will the existing tests change?

No. src/api.test.ts is the contract the agent works against, and the prompt says it must pass without edits. The defaultHook exists so a validation failure still answers 422 with the old body shape, and the 204 responses are declared as they are rather than changed to 404.

Does the current hono version in the example support @hono/zod-openapi?

The current @hono/zod-openapi release lists hono >= 4.10.0 as a peer, and the example's ^4.2.4 range resolves to a current 4.x on a fresh install. The agent reads the installed version from node_modules/hono/package.json after npm install and names it in the pull request.

Are the docs behind the basic auth?

No. src/index.ts applies basicAuth only to non-GET requests under /posts/*, and /api/doc and /api/ui are GET routes outside that path, so they are public. If the docs should be private, the reviewer adds the same middleware for those paths in index.ts.

What about the KV namespace in tests?

Nothing changes there. The vitest config reads wrangler.toml for the BLOG_EXAMPLE binding, as it does now, and the agent copies wrangler.example.toml into place for its own test run without committing it.

More Hono jobs

The same job on other stacks

Keep reading