菜单
Add or update OpenAPI 3.1 documentation for API endpoints in src/docs/. Use when the user asks to document endpoints, add Swagger/OpenAPI docs, or when a new resource or route was added without docs.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Add a new Express middleware to this project and wire it up correctly. Use when the user asks to add middleware — rate limiting, request guards, validation, logging enrichment, custom auth checks, etc.
Scaffold unit and integration tests for an existing resource or service. Use when the user asks to add tests, write tests, or improve test coverage for a specific resource, service, controller, or route.
Scaffold a complete new API resource (validation → repository → service → controller → route → container → app mount → OpenAPI → tests). Use when the user asks to add a new resource, entity, model, or endpoint group to the API.
Run a project-specific security audit of this Express API — auth, CSRF, rate limiting, headers, validation, secrets, and dependencies. Use when the user asks for a security review, audit, hardening pass, or before a release.
Update the Prisma schema to add a new model, add fields to an existing model, or change relations — then run migration and regenerate the client. Use when the user asks to add a field, add a model, change a relation, or update the database schema.
| name | add-openapi-docs |
| description | Add or update OpenAPI 3.1 documentation for API endpoints in src/docs/. Use when the user asks to document endpoints, add Swagger/OpenAPI docs, or when a new resource or route was added without 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.
<Name> = PascalCase singular (e.g. Note)<name> = camelCase singular (e.g. note)<names> = camelCase plural (e.g. notes)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.
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 limitauthErrors — shared 401/403/429 responses referencing #/components/schemas/ErrorResponsepaginationParams — page/limit query params on list endpointsFor every operation document:
tags, summary, description (mention auth + rate limit)examplesecurity: [{ bearerAuth: [] }, { cookieAuth: [] }] on protected endpointsExport const <name>Paths = { ... } keyed by path (e.g. '/notes', '/notes/{id}' — no base URL prefix; src/docs/index.ts handles that).
src/docs/index.ts)import { <name>Paths } from './paths/<name>.paths';
// merge into the paths object alongside authPaths, notePaths, healthPaths
If the resource introduces a new tag, add it to the tags array with a description.
pnpm full-check
pnpm dev # then open http://localhost:3000/api-docs and confirm the new endpoints render
Confirm every documented request/response matches the actual controller and validation behavior — docs that drift from code are worse than no docs.