Cursor接口文档编写的最佳实践：5个关键技巧让结果更像真实案例
生成可交付的接口文档，不能仅靠几条通用提示让Cursor自动输出。必须逐步注入真实项目信息——定义文件、错误响应结构、测试数据，缺一不可。以下四步可确保Cursor产出实打实可用的文档，而非泛化模板。
使用Cursor编写接口文档时，务必要求输出包含真实API路径、精确参数名称、实际状态码及业务错误示例的可交付成果，杜绝“/api/v1/user”“id: integer”这类通用占位符。
第一步：将项目Swagger/OpenAPI定义文件直接拖入对话框
定位项目根目录下的swagger.json、openapi.yaml或标注了@openapi的Java类（如UserController.java），直接拖入Cursor聊天窗口。这一步是保障后续输出准确性的根基——缺少真实的OpenAPI定义，Cursor会依据通用REST规范生成路径，例如/api/users，而你的项目实际路径可能是/internal/v2/account/profile。
拖入文件后立即追加指令：“基于此OpenAPI定义，生成一份面向前端开发者的接口文档。”从而锁定上下文范围。
第二步：明确文档受众与调用场景
有两种方法，核心在于清晰界定读者身份。
方法一：根据角色定制表达方式和信息颗粒度
“生成面向前端开发者的文档，需详细说明每个字段的必填属性、空值处理策略、枚举值完整映射（例如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中选择，不得自行编造；message使用中文且与业务场景紧密关联（例如‘优惠券已过期’而非‘invalid coupon’）；field字段仅填写实际存在的请求参数名称。”
此举可避免出现{ "error": "bad request" }等无效占位符。前端开发者可直接利用这些错误示例编写toast提示逻辑，无需额外转换。
第四步：关联真实测试数据生成联动
① 先让Cursor基于同一份OpenAPI定义生成5条符合schema的测试请求体（包含真实手机号、邮箱、时间范围）；
② 再追加指令：“将这5条请求体作为‘请求示例’嵌入文档对应接口下方，每条示例旁标注用途（例如‘正常创建用户’‘手机号重复场景’）”；
③ 最后补充：“响应示例必须与请求示例一一对应，且status字段值需逻辑匹配（例如手机号重复的请求，响应code应为40902）”。
完成这一步后，文档不再是静态描述，而是具备可验证行为链路的真实交付物——前端复制请求体即可直接调用，后端通过响应示例确认逻辑覆盖度。流程形成闭环，距离“真正可用”仅此一步。