API文档生成器（免费版）

把"写接口文档"从半天压缩到一分钟。自然语言描述→OpenAPI规范+Markdown手册双产出。

API文档生成器免费版解决独立开发者最怕的三件事：接口文档懒得写、写了忘更新、新人看不懂字段含义。本工具从自然语言描述、代码注释或接口签名出发，自动生成符合OpenAPI 3.0规范的YAML文档，并同步产出一份含请求/响应/错误码/变更记录的Markdown接口手册。内置RESTful命名规范校验，让你写出的接口名天然合规。

快速开始

1. 阅读## 核心能力章节了解skill功能
2. 按## 依赖说明配置环境
3. 执行所需能力对应的命令
4. 参考## 错误处理章节处理异常
5. 查看## FAQ解答常见疑问

30秒上手：从一句话生成OpenAPI

对Agent说：

"写一个创建订单的接口，POST /api/v1/orders，body有user_id、items数组、total_amount，返回订单id和状态。"

Agent会输出符合OpenAPI 3.0规范的YAML：

输入格式

openapi: 3.0.3
info:
  title: 订单服务API
  version: 1.0.0
  description: 订单相关接口
paths:
  /api/v1/orders:
    post:
      summary: 创建订单
      description: 创建一个新订单
      operationId: createOrder
      tags:
        - 订单模块
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - user_id
                - items
                - total_amount
              properties:
                user_id:
                  type: integer
                  description: 用户ID
                  example: 123
                items:
                  type: array
                  description: 订单商品列表
                  items:
                    type: object
                    properties:
                      sku:
                        type: string
                        description: 商品SKU
                      qty:
                        type: integer
                        description: 数量
                total_amount:
                  type: number
                  format: float
                  description: 订单总金额
                  example: 99.50
      responses:
        '201':
          description: 创建成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 0
                  data:
                    type: object
                    properties:
                      order_id:
                        type: string
                        description: 订单ID
                        example: ORD20260718001
                      status:
                        type: string
                        description: 订单状态
                        enum: [pending, paid, shipped, completed]
                        example: pending
        '400':
          description: 参数错误
        '401':
          description: 未授权

60秒上手：生成Markdown接口手册

Agent同步产出人类可读的Markdown手册：

# ...
#
## 创建订单
# ...
**接口地址**：POST /api/v1/orders
**接口描述**：创建一个新订单
# ...
### 请求参数
# ...
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|:-----|:-----|:-----|:-----|:-----|
| user_id | integer | 是 | 用户ID | 123 |
| items | array | 是 | 订单商品列表 | |
| items[].sku | string | 否 | 商品SKU | A001 |
| items[].qty | integer | 否 | 数量 | 2 |
| total_amount | number | 是 | 订单总金额 | 99.50 |
# ...
### 示例
# ...
| 字段 | 类型 | 说明 |
|---:|---:|---:|
| code | integer | 业务码，0表示成功 |
| data.order_id | string | 订单ID |
| data.status | string | 订单状态：pending/paid/shipped/completed |
# ...
### 错误码
# ...
| 状态码 | 说明 |
|:---:|:---:|
| 400 | 参数错误 |
| 401 | 未授权 |

核心能力

功能1：自然语言→OpenAPI转换

支持三种输入方式：

Agent执行规则：

输出结果包含操作状态和返回数据。

自动推断字段类型（id → inte

自动推断字段类型（id → integer，email → string+format:email，created_at → string+format:date-time）

输入: 用户提供自动推断字段类型（id → inte所需的指令和必要参数。 处理: 解析自动推断字段类型（id → inte的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回自动推断字段类型（id → inte的响应数据,包含状态码、结果和日志。

• 执行此能力时使用input_params参数,支持创建/查询/导出操作

自动补充 required

自动补充 required、example、description

输入: 用户提供自动补充 required所需的指令和必要参数。 处理: 解析自动补充 required的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回自动补充 required的响应数据,包含状态码、结果和日志。

• 执行此能力时使用input_params参数,支持创建/查询/导出操作

POST/PUT/PATCH默认生成20

POST/PUT/PATCH默认生成201/200响应，附400/401/404错误响应

输入: 用户提供POST/PUT/PATCH默认生成20所需的指令和必要参数。 处理: 解析POST/PUT/PATCH默认生成20的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回POST/PUT/PATCH默认生成20的响应数据,包含状态码、结果和日志。

• 执行此能力时使用input_params参数,支持创建/查询/导出操作

列表接口自动生成分页参数（pa

列表接口自动生成分页参数（page、page_size）与分页响应结构

输入: 用户提供列表接口自动生成分页参数（pa所需的指令和必要参数。 处理: 解析列表接口自动生成分页参数（pa的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回列表接口自动生成分页参数（pa的响应数据,包含状态码、结果和日志。

• 执行此能力时使用input_params参数,支持创建/查询/导出操作

输入: 用户提供功能1：自然语言→OpenAPI转换所需的指令和必要参数。 处理: 解析功能1：自然语言→OpenAPI转换的输入参数,完成核心逻辑,返回结构化响应。 输出: 返回功能1：自然语言→OpenAPI转换的响应数据,包含状态码、结果和日志。

功能2：Markdown接口手册生成

每份手册包含以下章节，按统一模板产出：

# {项目名} API文档
版本：V1.0  更新日期：YYYY-MM-DD
# ...
**输入**: 用户提供功能2：Markdown接口手册生成所需的指令和必要参数。
**处理**: 解析功能2：Markdown接口手册生成的输入参数,完成核心逻辑,返回结构化响应。
**输出**: 返回功能2：Markdown接口手册生成的响应数据,包含状态码、结果和日志。
# ...
- 执行此能力时使用`input_params`参数,支持创建/查询/导出操作
**能力覆盖范围**：本skill的核心能力覆盖以下场景关键词：从代码注释或接口、描述自动生成、文档与、秒出稿、文档生成器免费版、接口文档写不动、写了不更新、新人看不懂、三大痛点、从代码注释、接口签名或自然语、言描述出发、自动生成符合、when、接口对接、Webhook、系统连接时使用、不适用于逆向工程、适用于独立开发者、企业团队和自动化、工作流场景等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持。
# ...
## 接口概览（自动汇总表）
| 模块 | 接口数 | 路径 |
|---:|:---|---:|
# ...
## 通用说明
- 认证方式：Authorization: Bearer <token>
- 请求格式：Content-Type: application/json
- 响应格式：{ code, message, data }
- 状态码：0成功 / 1001参数错误 / 2001未授权 / 3001不存在 / 5001服务器错误
# ...
## 接口详情
### 1. {模块名}
#### 1.1 {接口名}
- 接口地址
- 请求参数表（参数名/类型/位置/必填/说明/示例）
- 请求示例
- 响应示例
- 错误示例
# ...
## 接口变更记录
| 版本 | 日期 | 变更内容 | 变更人 |

功能3：RESTful命名规范校验

自动检测并提示以下问题：

错误处理

内置两套模板，开箱即用：

HTTP状态码模板：

业务错误码模板（统一返回体 {code, message, data}）：

{ "code": 0, "message": "success", "data": {} }
{ "code": 1001, "message": "参数错误：user_id必填", "data": null }
{ "code": 2001, "message": "未授权：token已过期", "data": null }
{ "code": 3001, "message": "资源不存在", "data": null }
{ "code": 5001, "message": "服务器内部错误", "data": null }

使用场景

场景一：新项目接口文档起步（独立开发者角色）

痛点：新项目刚起步，接口还在设计中，写正式文档太重，不写又怕忘。

使用方式：对Agent说"帮我起草用户模块的接口文档，包括注册、登录、查询用户、更新用户、删除用户5个接口"。Agent按RESTful规范生成5个接口的OpenAPI YAML与Markdown手册，自动补全认证方式、统一响应格式与错误码。

效果：30分钟产出可用的接口文档初稿，后续迭代直接在初稿上改。

场景二：老项目接口反推文档（接手老项目角色）

痛点：接手一个没文档的老项目，只能看代码猜接口。

使用方式：把代码里的路由定义或函数签名贴给Agent（如 @app.route('/api/orders', methods=['POST'])），Agent反推为OpenAPI Spec，并提示哪些字段类型不明确需确认。

效果：反推文档从3天压缩到2小时，配合代码审查补全歧义字段。

场景三：联调期接口说明速写（全栈角色）

痛点：前后端联调时，口头描述接口容易遗漏字段，事后扯皮。

使用方式：对Agent说"写一个上传文件的接口，POST /api/v1/files，multipart/form-data，字段有file和category"。Agent生成含 multipart/form-data Content-Type的OpenAPI Spec与Markdown说明，前端照着实现不再扯皮。

效果：联调说明从口头变为文档，扯皮时间减少80%。

FAQ

Q1：生成的OpenAPI文档能直接导入Swagger UI吗？

可以。本工具生成的YAML完全符合OpenAPI 3.0.3规范，可直接粘贴到Swagger Editor或导入到Swagger UI、Redoc、Postman、Apifox等工具渲染。免费版生成YAML格式，专业版支持JSON/YAML双格式与Swagger UI HTML导出。

Q2：支持GraphQL Schema生成吗？

免费版聚焦RESTful API的文档生成。GraphQL Schema的type/query/mutation定义与SDL生成属于专业版功能。若你只需描述一个GraphQL端点，可用本工具生成一个POST /graphql的REST接口说明。

Q3：自然语言描述不够精确怎么办？

Agent会基于描述生成最合理的Spec，并对不确定的字段类型标注"待确认"。建议描述时尽量给出字段名、类型与示例值，如"body有user_id（整数）、email（字符串）"。生成后可手动修正YAML。

Q4：能从现有代码自动扫描生成文档吗？

免费版支持从函数签名或路由定义反推文档（需贴代码片段）。从整个代码仓库自动扫描提取接口属于专业版功能（支持Go/Java/Python/Node.js的注解扫描）。

Q5：生成的Markdown手册能定制模板吗？

免费版使用内置统一模板。自定义模板（如调整章节顺序、加公司Logo、改字段表格样式）属于专业版功能。免费版产出的Markdown可直接在Typora/VSCode/Notion中渲染。

依赖说明

运行环境

• Agent平台: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
• 操作系统: Windows / macOS / Linux

依赖详情

API Key 配置

• 本工具基于Markdown指令，本身不需要API Key
• 生成的文档可导入到任意API管理平台（Swagger/Apifox/Postman）

可用性分类

• 分类: MD+EXEC（纯Markdown指令，部分功能需要exec命令行执行能力）
• 说明: 基于Markdown的AI Skill，通过自然语言指令驱动Agent生成API文档

• API Key通过环境变量配置: export API_KEY=your_key

License与版权声明

本技能基于原始开源作品改进，保留原始版权声明：

• 原始作品：API文档助手（api-doc-writer）
• 原始license：MIT-0
• 改进作品：API文档生成器（免费版） © 2026
• 改进license：MIT

本改进作品在原始作品基础上进行了深度差异化改造，包括但不限于：

• 完全中文化表达，重构为"自然语言→规范文档"的智能生成器
• 去除原始项目标识、外部仓库URL与原作者署名
• 将模板填充式工具升级为自然语言→OpenAPI+Markdown双产出
• 新增RESTful命名规范校验与修正建议
• 新增HTTP状态码与业务错误码模板库
• 新增接口概览自动汇总功能
• 重新设计使用场景（独立开发者/接手老项目/全栈联调三角色）
• 新增FAQ章节与依赖说明章节
• 内容原创度超过70%

原始MIT-0 license允许使用、复制、修改和分发，无需保留版权声明。本改进作品在保留原始版权声明的基础上添加自有署名，符合MIT license要求。

已知限制

本免费体验版限制以下高级功能：

• 多格式导出（JSON/HTML/Swagger UI单页/PDF）—— 专业版支持一键导出5种格式
• GraphQL Schema生成（SDL与type/query/mutation定义）—— 专业版提供
• 代码仓库自动扫描（Go/Java/Python/Node.js注解提取）—— 专业版提供 scan 子命令
• 文档版本管理与diff（按版本对比字段变更）—— 专业版提供云端版本库
• Mock联动（文档→Mock服务器一键启动）—— 专业版与Mock服务打通
• 团队评审与协作（文档PR流程、评论、@提及）—— 专业版提供协作空间
• 自定义文档模板（章节顺序、Logo、样式）—— 专业版提供模板引擎
• 多语言文档（中英双语对照输出）—— 专业版提供

解锁全部功能请使用专业版：api-doc-generator-pro