OpenAPI Spec Generator

---
name: openapi-spec-gen
description: |
  Trigger when the user asks to generate an OpenAPI spec, document REST
  endpoints, or publish API docs. Phrases: "OpenAPI", "Swagger", "API
  spec", "document the API", "generate client SDK", "API schema".
allowed-tools:
  - Read
  - Write
  - Edit
  - Grep
  - Bash(npx *)
---

# OpenAPI Spec Generator

Produce a complete, accurate OpenAPI 3.1 spec for an HTTP API. Spec-first
when starting fresh, code-first when retrofitting an existing service.

## Prerequisites

- API implementation exists (retrofit) OR endpoint list drafted (new)
- OpenAPI 3.1 chosen (handles nullable, tuples, and JSON Schema 2020-12)
- Tooling: `@apidevtools/swagger-cli` for validation, Redocly or
  Swagger UI for preview

## Steps

1. **Pick the source of truth.** Two viable approaches:
   - **Spec-first:** hand-write `openapi.yaml`, generate server stubs
     and client SDKs from it. Best for cross-team contracts.
   - **Code-first:** decorate route handlers (zod-openapi, tsoa, Hono
     OpenAPI) and emit the spec at build time. Best for solo teams
     iterating fast.

2. **Start with `info`, `servers`, and auth:**
   ```yaml
   openapi: 3.1.0
   info:
     title: Acme API
     version: 1.4.0
     description: |
       Public HTTP API for Acme. See https://docs.acme.com for guides.
   servers:
     - url: https://api.acme.com/v1
   components:
     securitySchemes:
       bearerAuth:
         type: http
         scheme: bearer
   security:
     - bearerAuth: []
   ```

3. **One path per endpoint, grouped by tag.** Tags map to sidebar sections
   in Redoc. Keep paths RESTful: `/users/{id}/posts`, not
   `/getUserPosts`.

4. **Reusable schemas under `components/schemas`.** Never inline a
   response shape that appears more than once. Ref it:
   ```yaml
   responses:
     '200':
       content:
         application/json:
           schema:
             \$ref: '#/components/schemas/User'
   ```

5. **Document every error shape.** 400, 401, 403, 404, 409, 422, 429,
   500. Use a `Problem` schema (RFC 7807) for consistency across
   endpoints.

6. **Examples beat descriptions.** Every request body and response
   should have at least one realistic `example`. Tools render them;
   users copy-paste them.

7. **Validate before publishing.**
   ```bash
   npx @apidevtools/swagger-cli validate openapi.yaml
   npx @redocly/cli lint openapi.yaml
   ```

8. **Version the spec with the API.** Tag `openapi.yaml` in git with
   the release version. Do not mutate history; publish v1.4.0 as a
   separate file or branch.

## Patterns that work

- Zod to OpenAPI via `@asteasolutions/zod-to-openapi` keeps schema and
  runtime validation in sync
- Generate TypeScript client via `openapi-typescript` or `orval` on
  every spec change
- Redoc for public docs, Swagger UI for internal "try it now" console
- Contract tests that hit the real API and validate responses against
  the spec

## Anti-patterns

- Hand-maintaining the spec while the code drifts
- Leaving error responses undocumented (consumers guess)
- Using `anyOf` without `discriminator` (generators produce useless types)
- Publishing a v1 spec with `additionalProperties: true` everywhere
  (breaks client validation)

## Output

- `openapi.yaml` validated and linted
- Generated TypeScript client in `packages/api-client`
- Redoc static site deployed at `/docs`
- CI check that fails if the spec is invalid or drifts from code