写接口文档这件事，后端开发大概经历过三个阶段：
第一阶段：口头约定。“你调这个接口就行，参数我发你了。"——然后前端一脸懵。
第二阶段：手写 Markdown。每次改接口都要同步文档，改完就忘。
第三阶段：用工具自动生成。代码和文档始终一致，这才是正道。
但自动化工具的注解写法也很繁琐。这时候 AI 就派上用场了。
为什么需要 AI 生成接口文档？
传统自动生成工具（比如 Swagger/OpenAPI 注解）有几个痛点：
- 注解写在代码里，干扰业务逻辑
- 参数描述全靠手填，容易遗漏
- 修改接口后要重新跑生成命令
- 不支持自然语言补充说明
AI 的介入改变了这个局面。你只需要提供代码或接口列表，AI 就能生成结构化的 OpenAPI 文档。
方法一：用 AI 从现有代码生成文档
这是最简单的用法。把控制器代码贴给 AI，让它输出 OpenAPI YAML。
以 FastAPI 为例：
# main.py
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/users/{user_id}")
def get_user(user_id: int, include_posts: bool = False):
"""获取用户信息"""
pass
@app.post("/users")
def create_user(name: str, email: str, age: int = None):
"""创建新用户"""
pass
把这段代码发给 AI，附上提示词：
请根据以下 Python FastAPI 代码生成 OpenAPI 3.0 YAML 格式的接口文档，包含请求参数说明、响应示例和错误码。
AI 会输出类似这样的结果：
openapi: 3.0.3
info:
title: User API
version: 1.0.0
paths:
/users/{user_id}:
get:
summary: 获取用户信息
parameters:
- name: user_id
in: path
required: true
schema:
type: integer
- name: include_posts
in: query
schema:
type: boolean
default: false
responses:
'200':
description: 成功返回用户信息
'404':
description: 用户不存在
/users:
post:
summary: 创建新用户
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
email:
type: string
format: email
age:
type: integer
nullable: true
responses:
'201':
description: 创建成功
这个过程通常只需要 10 秒。
方法二：用 AI 补充文档描述
光有结构不够，文档的核心是"说清楚”。AI 最擅长的就是写说明文字。
比如你有一个复杂的查询接口：
GET /api/reports/sales?start_date=2026-01-01&end_date=2026-06-30&group_by=month&format=csv
让 AI 写参数说明：
请为以下接口编写详细的参数说明文档，包括每个参数的含义、取值范围、默认值和示例。
AI 会输出：
| 参数 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
| start_date | string | 是 | 统计起始日期，格式 YYYY-MM-DD | 2026-01-01 |
| end_date | string | 是 | 统计截止日期，格式 YYYY-MM-DD | 2026-06-30 |
| group_by | string | 否 | 分组维度：day/week/month/quarter | month |
| format | string | 否 | 输出格式：json/csv/excel | csv |
方法三：用 AI 将旧接口转为 OpenAPI
很多老项目没有接口文档，只有代码。用 AI 可以批量转换。
思路很简单：
- 导出所有路由文件
- 让 AI 逐文件生成 OpenAPI 片段
- 合并成一个完整的文档
以 Express.js 为例：
// routes/users.js
router.get('/users/:id', UserController.get);
router.post('/users', UserController.create);
router.put('/users/:id', UserController.update);
router.delete('/users/:id', UserController.remove);
配合 AI 提示词：
以下是一个 Express.js 路由文件，请为每个路由生成对应的 OpenAPI 3.0 路径定义。假设 UserController 的方法分别对应 CRUD 操作，用户对象包含 id、name、email、createdAt 字段。
方法四：用 AI 生成 Mock 数据
文档写好了，前端需要联调数据。AI 可以直接生成符合规范的 Mock 响应。
根据以下 OpenAPI 定义的 /users/{user_id} 接口，生成 3 条符合响应格式的 Mock JSON 数据。
输出：
{
"id": 1024,
"name": "张明",
"email": "zhangming@example.com",
"age": 28,
"created_at": "2026-03-15T10:30:00Z",
"posts": [
{
"id": 501,
"title": "AI 辅助开发实践",
"views": 1234
}
]
}
前端拿到数据就能开始开发了，不用等后端写完。
推荐工具组合
手动用 AI 生成虽然快，但团队规模化使用时需要自动化。以下是几种方案：
方案一：AI + OpenAPI Generator
用 AI 生成初始文档，然后用 OpenAPI Generator 自动生成客户端 SDK。
# 安装
npm install @openapitools/openapi-generator-cli -g
# 生成 TypeScript 客户端
openapi-generator-cli generate \
-i api.yaml \
-g typescript-axios \
-o ./src/api
方案二：AI + Redoc/Swagger UI
生成文档后直接渲染为可视化界面。
# 用 Redoc 渲染
npx redoc-cli serve api.yaml
# 访问 http://localhost:8080
方案三：AI + Postman Collection
让 AI 同时生成 OpenAPI 文档和 Postman 集合，方便测试。
请将以下 OpenAPI 文档转换为 Postman Collection v2.1 格式。
最佳实践
1. 保持文档和代码同步
AI 生成的文档不是一劳永逸的。建议：
- 每次接口变更时重新运行 AI 生成
- 在 CI 流程中加入文档校验
- 用 Git hook 在提交前检查文档更新
2. 让 AI 写错误码说明
很多团队只写成功响应，忽略了错误处理。让 AI 补充：
responses:
'400':
description: 请求参数错误
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: 未授权
'404':
description: 资源不存在
'429':
description: 请求过于频繁
3. 用 AI 做文档审查
写完文档后，让 AI 检查：
请审查以下 OpenAPI 文档，找出以下问题：缺少必填参数说明、响应格式不一致、缺少错误码定义、示例数据不合理。
4. 版本化管理
接口文档也要打版本标签：
docs/openapi/v1.yaml # 稳定版
docs/openapi/v2.yaml # 新版
docs/openapi/latest.yaml # 最新（可能不稳定）
总结
AI 生成接口文档的核心价值不是"替代人"，而是"减少重复劳动"。结构化的 OpenAPI 定义让 AI 来处理，自然语言描述让 AI 来润色，Mock 数据和客户端 SDK 让 AI 来生成。
把耗时的工作交给 AI，你只需要审核和调整。这才是高效的做法。
你的团队是怎么管理接口文档的？手写还是自动生成？欢迎交流。