Skip to content
版本 v2.0.0更新于 2026-09-17
documentationapiopenapi

生成 API 文档 ​

适用场景 ​

接口写完后生成可直接交给前端/测试使用的接口文档,要求示例数据真实可解析。

输入变量 ​

变量含义示例
[api_name]API 名称用户管理 API
[endpoints]接口列表及说明POST /users 创建用户
[schemas]请求/响应数据结构User 对象字段定义

提示词模板 ​

把下面整段复制给 AI,替换 [占位符] 后使用。

你是一名有 10 年以上经验的工程师,写的接口文档以"拿到就能联调"为标准。示例数据必须是合法可解析的内容;接口定义里没有的字段不要编造。

【任务】 为以下 API 生成完整的接口文档。

【API 信息】 API 名称:[api_name] 接口列表:[endpoints] 数据结构:[schemas]

【约束】 必须:

  • 每个接口包含:路径与方法、参数表(参数名/类型/必填/说明)、请求示例、响应示例
  • 请求与响应示例用合法 JSON 代码块,字段与数据结构定义严格一致
  • 参数用 Markdown 表格展示
  • 包含错误码对照表(错误码、含义、处理建议)
  • 包含认证方式说明
  • 路径命名遵循 RESTful 习惯,资源用复数名词

禁止:

  • 使用"省略"、"同上"之类的占位写法
  • 编造接口未定义的字段或错误码
  • 输出与接口无关的章节

【输出】 按以下顺序组织:

  1. 接口总览(表格:方法、路径、说明)
  2. 每个接口的详细说明
  3. 数据模型说明
  4. 错误码对照表

使用示例 ​

输入: api_name: 用户管理 API endpoints: POST /users 创建用户、GET /users/{id} 查询用户 schemas: User(id, name, email, created_at)

AI 输出: 接口总览表 + 两个接口的参数表与合法 JSON 示例 + User 模型说明 + 错误码对照表,可直接用于联调。

迭代记录 ​

  • 1.0.0 (2026-09-03): 初始版本
  • 2.0.0 (2026-09-17): 按新模板重构,增加"示例必须合法可解析""禁止编造字段"约束