必须用真实OpenAPI定义生成接口文档：第一步拖入swagger.json等文件；第二步指定前端读者及调用上下文；第三步注入真实错误结构并约束code和message；第四步绑定测试数据实现请求与响应一一对应。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
用Cursor生成接口文档时，必须让它输出带真实路径、真实参数名、真实状态码和真实错误示例的可交付物，而不是“/api/v1/user”“id: integer”这种泛化模板。
第一步：把Swagger/OpenAPI文件拖进聊天框
找到项目根目录下的swagger.json、openapi.yaml或@openapi注解的Java类（如UserController.java），直接拖进Cursor聊天窗口。这一步是所有后续准确性的前提——【没有真实OpenAPI定义，Cursor会按通用REST规范生成，path里全是/api/users，而你项目实际是/internal/v2/account/profile】。
拖入后立刻跟一句：“基于此OpenAPI定义，生成一份面向前端开发者的接口文档。”
Agents 正在你的整个代码库中处理越来越复杂、运行时间更长的任务。本次版本引入了新的 agent 框架改进，以实现更好的上下文管理，并在编辑器和 CLI 中带来了许多提升使用体验的修复。
第二步：指定文档读者与使用场景
方法一：按角色定制语气和细节粒度
“生成给前端同学看的文档，重点写清楚每个字段是否必填、空值怎么处理、枚举值具体有哪些（比如status字段要列出0=待提交,1=审核中,2=已驳回）、响应体里data结构嵌套几层。”
方法二：按调用环节补充上下文
“这是用于登录后调用的接口，请求头必须带X-Auth-Token和X-Client-Version，文档里要显式写出这两个header，并标注版本号格式为‘1.2.3’。”
注意：不写清楚读者角色，Cursor默认输出技术文档体，满篇HTTP状态码定义却漏掉“前端传参时date_range要用ISO 8601字符串，不能传时间戳”这种关键约束。
第三步：强制注入真实错误案例
第一步：确认项目已有统一错误格式
翻出/src/lib/error/ApiError.ts或全局异常处理器，复制其中的错误响应结构，例如：
{ "code": 40001, "message": "手机号格式不正确", "field": "phone" }
第二步：在提示词中粘贴该结构，并追加指令
“所有错误响应示例必须严格按以上结构生成，code值从项目error-code.md中选取，禁止编造code；message必须是中文，且与业务强相关（如‘优惠券已过期’而非‘invalid coupon’）；field字段只填真实存在的请求参数名。”
这能防止生成{ "error": "bad request" }这种无效占位符，确保前端能直接拿去写toast提示逻辑。
第四步：绑定真实测试数据生成联动
① 先让Cursor基于同一份OpenAPI定义生成5条符合schema的测试请求体（含真实手机号、真实邮箱、真实时间范围）；
② 再追加指令：“将这5条请求体作为‘请求示例’嵌入文档对应接口下方，每条示例旁标注用途（如‘正常创建用户’‘手机号重复场景’）”；
③ 最后补一句：“响应示例必须与请求示例一一对应，且status字段值要匹配（比如手机号重复的请求，响应code必须是40902）。”
这一步做完，文档就不再是静态描述，而是自带可验证行为链路的真实交付物——前端复制请求体就能跑通，后端对照响应示例就能确认逻辑覆盖度。
