从代码生成 OpenAPI 接口规范
读取路由、校验器、序列化器和错误处理逻辑,生成准确的 OpenAPI 文件并报告接口覆盖与代码缺口。
完整提示词
<context>
A hand-written spec that disagrees with the API is worse than none: client generators, contract tests and partners all trust it. The facts live in several places: the router (paths, methods), middleware (auth, rate limits, body size), validators and models (request schemas, required fields, formats, enums), serializers (the real response shape, which often differs from the database model), and error handlers (the actual error body and status codes). Common mistakes are marking every field optional, missing `nullable` versus absent, forgetting error responses, documenting the ORM model instead of the serializer, and inventing examples. If the framework can generate a spec (FastAPI, NestJS Swagger, springdoc, drf-spectacular), extending the generator beats writing a parallel file that will drift.
</context>
<task>
Write an OpenAPI {{version}} spec for {{target}}.
1. Check whether the framework already emits a spec or has a plugin for it. If so, say so and propose using it, then still produce the spec only if the user wants a standalone file.
2. List every route: method, path, path parameters, the handler, and the middleware applied (auth, rate limiting, content types). Skip internal or admin routes unless they are in scope, and list what you skipped.
3. For each operation, derive from the code: `operationId` (from the handler name), query, header and path parameters with types and constraints, request body schema from the validator, success responses from the serializer, and every error status the handler or shared error middleware can return with its body shape.
4. Put shared shapes under `components/schemas` and reuse them with `$ref`. Mark `required` fields and nullability exactly as the validator and serializer enforce them. Use `enum`, `format`, `minimum`, `maxLength` only where the code enforces them.
5. Define `securitySchemes` from the auth middleware and apply `security` per operation, including public endpoints as `security: []`.
6. Add examples taken from tests, fixtures or real responses. If you can run the service or its tests, compare a few real responses against the spec and fix mismatches.
7. Validate the file with a linter if available (for example Spectral or Redocly CLI) and report the result.
</task>
<constraints>
- Describe what the code does, not what would be nice. Never invent endpoints, fields, status codes or limits.
- Where the code is ambiguous (dynamic routes, untyped responses), add the best-supported shape with `x-todo` or a description note and list it under "Gaps and guesses".
- Do not change the API code. Report inconsistencies (for example two error formats) instead of hiding them in the spec.
- Keep descriptions short in this pass; the goal is a correct contract.
{{> guardrails/investigate-before-answering}}
</constraints>
<output_format>
Write the spec file (for example `openapi.yaml`). Then reply with:
## Spec written
Path, OpenAPI version, number of operations and schemas, lint result.
## Coverage
Routes included and routes skipped, with why.
## Gaps and guesses
Every place where the spec is inferred rather than read from code.
## API inconsistencies
Differences in naming, error formats, pagination or status codes across endpoints. Write "None" if there are none.
</output_format>可替换内容
- {{version}}
- {{target}}
- {{> guardrails/investigate-before-answering}}
分类与标签
编程开发、OpenAPI、接口文档、API 规范