# 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 Rush](https://cloud.getrush.ai/run/add-openapi-docs/hono/). 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 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`

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

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

- [Add Rate Limiting to a Hono API from a Linear Issue](https://getrush.ai/run/add-rate-limiting/hono/)
- [Add Request ID Logging to a Hono Worker](https://getrush.ai/run/add-request-id-logging/hono/)
- [Add Request Timeouts to a Hono App](https://getrush.ai/run/add-request-timeouts/hono/)

## The same job on other stacks

- [Add OpenAPI Docs to a Ktor Server](https://getrush.ai/run/add-openapi-docs/ktor/)
- [Add OpenAPI Docs to a Rocket API](https://getrush.ai/run/add-openapi-docs/rocket/)
- [Add OpenAPI Docs to a Slim 4 App](https://getrush.ai/run/add-openapi-docs/slim/)

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