Api Doc Generator Free

自动从代码注释、接口签名或自然语言描述生成符合OpenAPI 3.0规范的API文档及Markdown接口手册，支持RESTful校验。

Install

openclaw skills install @thcjp/api-doc-generator-free

API文档生成器（免费版）

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

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

快速开始

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

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

对Agent说：

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

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

输入格式

参数名	类型	必填	说明
input	string	是	API文档生成器(免费版)处理的输入数据或指令
options	object	否	附加配置选项,如模式选择、格式偏好等
callback_url	string	否	异步处理完成后的回调通知URL

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手册：

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转换

支持三种输入方式：

输入方式	示例	适用场景
自然语言描述	"写一个分页查询用户的接口"	快速起草
代码函数签名	`def get_user(user_id: int) -> User:`	老项目反推文档
现有curl命令	`curl -X POST ... -d '{"a":1}'`	接口已存在，补文档

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接口手册生成

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

text

# {项目名} 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命名规范校验

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

检测项	错误示例	修正建议
URL用名词复数	`/getUser`	`/users`
用小写连字符	`/orderDetails`	`/order-details`
资源层级清晰	`/api/users/orders/items`	`/users/{id}/orders/{id}/items`
HTTP方法语义正确	POST `/users/1`（应为PUT/PATCH）	PUT `/users/1`
状态码语义正确	返回200创建资源	应返回201
版本号在URL中	`/users` 无版本	`/v1/users`

错误处理

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

HTTP状态码模板：

类别	状态码	语义	使用场景	处理方式
2xx	200	成功	GET查询成功	对照依赖说明章节逐项验证配置项,确认环境变量已正确设置后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令
2xx	201	创建成功	POST创建资源成功	对照依赖说明章节逐项验证配置项,确认环境变量已正确设置后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令
2xx	204	无内容	DELETE删除成功	对照依赖说明章节逐项验证配置项,确认环境变量已正确设置后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令
4xx	400	参数错误	请求体格式错/缺必填	对照依赖说明章节逐项验证配置项,确认环境变量已正确设置后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令
4xx	401	未授权	Token缺失/过期	对照依赖说明章节逐项验证配置项,确认环境变量已正确设置后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令
4xx	403	禁止访问	权限不足	对照依赖说明章节逐项验证配置项,确认环境变量已正确设置后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令
4xx	404	不存在	资源ID无效	对照依赖说明章节逐项验证配置项,确认环境变量已正确设置后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令
4xx	409	冲突	资源已存在/状态冲突	对照依赖说明章节逐项验证配置项,确认环境变量已正确设置后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令
4xx	422	业务校验失败	字段格式对但业务不通过	对照依赖说明章节逐项验证配置项,确认环境变量已正确设置后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令
4xx	429	限流	触发速率限制	对照依赖说明章节逐项验证配置项,确认环境变量已正确设置后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令
5xx	500	服务器错误	上游异常	对照依赖说明章节逐项验证配置项,确认环境变量已正确设置后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令
5xx	503	服务不可用	维护中/降级	对照依赖说明章节逐项验证配置项,确认环境变量已正确设置后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令

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

json

{ "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

依赖详情

依赖项	类型	是否必需	获取方式
LLM API	API	必需	由Agent平台内置LLM提供（免费版路由GPT-4o-mini）
文本编辑器	工具	推荐	VSCode/Typora用于查看与编辑生成的YAML/Markdown

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
改进license：MIT

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

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

已知限制

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

多格式导出（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