AI 接口文档生成器
Markdown / OpenAPI概述
AI 接口文档生成器是什么？
将接口用途、请求参数和 JSON 示例整理成结构清晰的 API 文档。 你只需要说明接口“接收什么、完成什么、返回什么”，AI 就会帮助编写参数说明、请求体与响应结构， 并支持导出 Markdown、OpenAPI JSON 和 HTML，便于前后端协作、接口评审与项目交付。
用自然语言说明接口用途，配合示例整理文档，不必从空白文档开始编写。
展示参数位置、字段类型、必填情况、嵌套结构和请求响应示例。
同一份结果可复制或下载为不同格式，满足代码仓库、接口工具和独立阅读需求。
如何使用？
支持 GET、POST、PUT、PATCH、DELETE。
路径填写为 /api/users，路径参数使用 /api/users/{id}。
不需要填写域名，也不要将 ?page=1 等查询字符串拼进路径。
写清楚接口完成的操作、字段含义、数据类型和必填条件。 例如：“根据用户编号查询详情，id 为必填整数，返回用户编号、名称和邮箱。” 需要记录分页、枚举、取值范围等规则时，也应在此明确说明。
展开“请求与响应示例 / 选项”，粘贴合法 JSON。 本工具将 GET、DELETE 的请求示例作为查询参数； POST、PUT、PATCH 的请求示例作为 JSON 请求体。 还可以选择认证方式及示例对应的响应状态码。
点击“生成文档”，或在接口说明框中按 Ctrl / ⌘ + Enter。 完成后在右侧核对文档，选择导出格式，再点击复制或下载。 生成过程中可以停止；修改输入后需要重新生成。
填写示例：创建用户接口
下面是一组可以参考的接口信息。示例邮箱使用 example.com，便于作为演示数据。
接口说明： 创建用户。请求体 name 为必填字符串，email 为可选字符串。 成功返回用户 id、name 和 email，响应状态码为 201。
{
"name": "示例用户",
"email": "user@example.com"
}
{
"id": 1,
"name": "示例用户",
"email": "user@example.com"
}
示例提供的是数据形态，不能单独证明字段是否必填。
如果 name 必须提交，应在接口说明中写明，而不是仅依赖请求示例。
应该选择哪种导出格式？
| 格式 | 适合场景 | 使用方式 |
|---|---|---|
| Markdown | 项目仓库、README、团队知识库 | 下载 .md 文件，或复制到支持 Markdown 的文档平台继续编辑。 |
| OpenAPI JSON | 接口定义交换、文档工具导入 | 导出 OpenAPI 3.0.3 文档，交给支持该版本的工具使用。 |
| HTML | 独立阅读、发送给同事或客户 | 下载静态 HTML 文件，使用浏览器打开，无需安装文档软件。 |
文档会整理哪些内容？
- 接口概况：名称、用途、请求方法和接口路径。
- 请求参数：path、query、header、cookie 参数的位置、类型、必填情况与示例。
- JSON 请求体：字段结构、嵌套对象、数组及请求示例。
- 响应定义：状态码、字段类型、结构说明和响应示例。
- 认证声明：根据页面选择记录 Bearer Token 或 X-API-Key，不生成实际凭证。
- 必要补充：已知约束、需要确认的信息及有依据的说明。
常见问题
没有请求或响应示例，也能生成吗？
可以先用文字描述，但应尽量明确字段名称、类型及业务规则。 关键信息不足时，工具可能提示补充信息，而不是生成不确定的完整文档。 提供精简、准确的 JSON 示例，通常更便于整理字段结构。
为什么提示 JSON 格式错误？
JSON 的键名和字符串需要使用双引号，不支持注释、末尾多余逗号或单引号字符串。
例如应填写 {"id":1}，而不是 {id:1}。
示例为空时可以不填写，不必输入占位说明文字。
很长的数字 ID 应该怎么填写？
超出 JavaScript 安全整数范围的 ID 应写成字符串，
例如 {"id":"9007199254740993"}。
工具会拒绝可能丢失精度的数字，避免文档中的 ID 被悄悄改写。
为什么提示内容超过接口限制？
长度按完整 AI 请求的 UTF-8 字节数计算，包含接口信息和示例。 可以删除示例中的重复记录、缩短说明，保留具有代表性的一条数据。 实际可提交长度以页面显示的字节上限为准。
选择 Bearer Token 后，需要输入真实 token 吗？
不需要。该选项只用于在文档中声明认证方式； X-API-Key 选项同样只记录认证定义。 工具不会登录接口或验证凭证是否有效。
生成的文档是否意味着接口已经测试通过？
不意味着。工具根据你提供的信息编写文档，不会实际调用接口， 也不能确认后端实现、权限、限流或错误处理是否与文档一致。 交付前应对照真实接口核对参数、必填条件和响应结构。
接口信息会保存在哪里？
点击生成时，接口说明和示例会提交到站点的 AI 服务。 页面不会将这些内容写入本地持久存储；文档预览、格式切换和文件导出在浏览器中完成。 离开页面时会终止当前请求并清除页面运行态。
适用范围
适合单个 JSON / REST 接口的文档草稿、前后端沟通和接口交付。 当前版本不包含真实接口调试、多接口项目导入、文件上传接口或 WebSocket 文档生成。