---
name: openapi-docs
description: Generates or updates an OpenAPI 3.1 YAML spec by reading the project's route handlers, request validators and response code. Use when the user asks to document an HTTP API, create or update openapi.yaml or swagger docs, or check whether the API spec matches the code.
---

# OpenAPI docs from code

Scope: `$ARGUMENTS`. It may be a source path, a route prefix, or an existing spec file path. If it names a `.yaml`/`.yml`/`.json` file, update that file; otherwise write `openapi.yaml` at the repo root (or update it if present).

## 1. Locate routes

Identify the framework from dependencies and find where routes are registered. Read the router code; follow mounted sub-routers and prefixes so the full path is correct. Only document routes reachable from the app's router.

## 2. Extract each operation

For each route record, with the source location:
- Method and full path. Convert path params to OpenAPI form (`:id` or `<id>` or `{id}` -> `{id}`).
- Path, query and header parameters, with type and whether required.
- Request body: derive the schema from the validator (Zod, Joi, Yup, class-validator DTOs, Pydantic models, Django REST serializers, Laravel Form Requests, Go struct tags). Include `required`, enums, min/max, formats where the validator states them.
- Responses: each status code the handler or its middleware can return, and the body shape for each. Include error responses produced by shared error handlers if you can trace them.
- Security: which auth middleware or dependency applies.

If a value cannot be traced to code, do not guess. Add it to the gaps list.

## 3. Write the spec

- `openapi: 3.1.0`. Keep any existing `info`, `servers`, tags, descriptions and examples written by people.
- Put shapes used more than once under `components/schemas` and reference them with `$ref`.
- Use `operationId` values in camelCase derived from the handler name when one exists.
- Define auth under `components/securitySchemes` only for schemes the code actually implements.
- Do not invent example values that look like real customer data. Omit examples unless they are in the code or tests.
- Keep operations sorted by path, then method, so diffs stay small.

## 4. Validate

If Node is available, run `npx @redocly/cli lint <spec>` and fix structural errors. If not, check that every `$ref` resolves and the YAML parses.

## 5. Report

```
Spec: <path>
Operations added: <n>, updated: <n>, unchanged: <n>
Gaps (need a human):
- <METHOD path>: <what is missing and why> (`source:line`)
Routes in spec but not found in code: <list, not deleted>
```

Never delete operations from an existing spec automatically. List them for the user instead.