OpenAPI 3.1 spec generator from your existing route handlers
A Claude Code skill that reads your HTTP routes, validators and response code, then writes or updates an OpenAPI 3.1 YAML file that matches what the server actually does, and lists anything it could not determine.
Skill in Engineering by AISkillHub Library
What it does
API docs drift because they are written separately from the code. This skill makes Claude Code derive an OpenAPI 3.1 document from the source of truth: route definitions, request validation, and the code that builds responses.
**What it does** - Finds route definitions for common frameworks (Express, Fastify, NestJS, Next.js route handlers, FastAPI, Flask, Django REST Framework, Laravel, Rails, Go `net/http` and popular routers) by reading the code, not by guessing from file names. - For each operation it records the method, path, path and query parameters, request body schema (from Zod, Pydantic, Joi, Form Requests, serializers or struct tags), success and error responses, and auth requirements. - Merges into an existing spec without deleting hand-written descriptions or examples. - Puts reusable shapes in `components/schemas`. - Lints the result with Redocly CLI if Node is available.
**Accuracy rules** Everything in the spec must trace to code. When a response shape is built dynamically or a status code cannot be determined, it is left out of the spec and listed in a "gaps" report so you can fill it in. It does not invent example values that look like real data.
**What it will not do** It does not generate client SDKs, change your routes, or document endpoints that are not reachable from the router.
**Example** `/openapi-docs src/routes/orders.ts` adds `GET /orders`, `POST /orders` and `GET /orders/{id}` to `openapi.yaml`, with a `CreateOrderRequest` schema taken from the Zod validator, and reports one gap: the 409 response body on `POST /orders` is built from an error class it could not resolve.
How to use it
1. Save the file below as `.claude/skills/openapi-docs/SKILL.md` in your repository. 2. Run `/openapi-docs` for the whole API, or `/openapi-docs <path or route prefix>` to limit the scope (recommended for large APIs). 3. By default it writes `openapi.yaml` at the repository root. If you already keep a spec elsewhere, name it: `/openapi-docs docs/api/openapi.yaml`. 4. Review the gaps list at the end and fill those parts in by hand. 5. Optional: lint with `npx @redocly/cli lint openapi.yaml` in CI.
Files
Save each file at the path shown, relative to your project root.