back
loading skill details...
自动从代码注释、接口签名或自然语言描述生成符合OpenAPI 3.0规范的API文档及Markdown接口手册，支持RESTful校验。
---
slug: api-doc-generator-free
name: api-doc-generator-free
version: 1.0.0
displayName: API文档生成器(免费版)
summary: 从代码注释或接口描述自动生成OpenAPI 3.0文档与Markdown接口手册，60秒出稿。
license: Proprietary
edition: free
description: API文档生成器免费版解决"接口文档写不动、写了不更新、新人看不懂"三大痛点。从代码注释、接口签名或自然语言描述出发，自动生成符合OpenAPI
3。Use when 需要API集成、接口对接、Webhook配置、系统连接时使用。不适用于逆向工程闭源API。适用于独立开发者、企业团队和自动化工作流场景。
tags:
- API文档
- OpenAPI
- 接口规范
tools:
- - read
- exec
homepage: https://skillhub.cn
pricing_tier: "L2-标准级"
pricing_model: per_use
suggested_price: "19.9 CNY/per_use"
tools: ["read", "write", "exec"]
tags: "API,接口,开发工具"
---
# 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：
## 输入格式
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| 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
- 改进作品：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
don't have the plugin yet? install it then click "run inline in claude" again.