add-openapi-docs

When the user asks to document an endpoint or resource, follow this sequence. The spec is assembled at import time in src/docs/index.ts and served by swagger-ui-express at /api-docs.

Variables

• <Name> = PascalCase singular (e.g. Note)
• <name> = camelCase singular (e.g. note)
• <names> = camelCase plural (e.g. notes)

Step 1 — Schemas (src/docs/schemas.ts)

Add component schemas for the resource:

• <Name> — the response entity shape (must match <Name>ResponseDTO in src/types/, never include password/token/internal fields)
• Create<Name>Request and Update<Name>Request — must match the Zod schemas in src/validations/<name>.validation.ts exactly (required fields, min/max lengths, formats)

Reuse the existing shared schemas: ErrorResponse, PaginatedResponse, SuccessResponse.

Step 2 — Paths (src/docs/paths/<name>.paths.ts)

Copy the structure of src/docs/paths/note.paths.ts. It defines reusable local constants — keep the same ones:

• csrfHeader — required x-csrf-token header parameter on every mutating operation (POST/PUT/PATCH/DELETE)
• rateLimitHeaders — X-RateLimit-* response headers with the route group's actual limit
• authErrors — shared 401/403/429 responses referencing #/components/schemas/ErrorResponse
• paginationParams — page/limit query params on list endpoints

For every operation document:

• tags, summary, description (mention auth + rate limit)
• Request body referencing the component schema, with a realistic example
• All response codes actually produced: 200/201, 400 (validation), 401, 403 (CSRF or ownership), 404, 409 (conflict), 429
• security: [{ bearerAuth: [] }, { cookieAuth: [] }] on protected endpoints

Export const <name>Paths = { ... } keyed by path (e.g. '/notes', '/notes/{id}' — no base URL prefix; src/docs/index.ts handles that).

Step 3 — Register (src/docs/index.ts)

import { <name>Paths } from './paths/<name>.paths';
// merge into the paths object alongside authPaths, notePaths, healthPaths