OpenCode API文档生成:让文档和代码同步更新,还要什么自行车?

“把这个接口的文档更新一下。”

产品经理又双叒叕让我更新API文档。我打开文档一看，好家伙，上次更新还是半年前，接口参数早变了三轮了。

我陷入了沉思。这文档：

• 参数对不上
• 返回值没写
• 示例代码是错的
• 错误码更是完全没有

这文档，写了等于没写。

直到我发现了OpenCode的文档生成能力。这玩意儿，简直是文档党的救命稻草。

一、文档为什么会过时？

1.1 手动写文档的痛

相信我，你不是一个人。

十个开发九个烦文档，还有一个根本不做。为什么会这样？

原因很简单：文档是手动写的，而代码是天天改的。

// 代码改了3轮了public User getUserById(Long id, String include){// 新增了 include 参数，可以指定返回哪些字段// 旧文档完全不知道}// 文档还是半年前的/** * 根据ID获取用户信息 * @param id 用户ID * @return 用户信息 */

你说气人不气人？文档和代码，就像两条平行线，永远追不上。

1.2 文档过时的后果

• 联调靠吼：接口对不上，开发者只能当面问
• 前端背锅：参数错了，前端报错怪后端
• 测试崩溃：文档没写清楚，测试只能靠猜
• 交接翻车：新人来了，看文档完全没用

文档最大的价值不是”有”，而是”准”。

二、OpenCode文档生成：AI来帮忙

2.1 一句话生成文档

在OpenCode里，生成文档有多简单？

# 启动OpenCodeopencode# 直接让AI生成文档> 为这个项目生成API文档

没了。就这么简单。

AI会自动：

1. 扫描所有接口代码
2. 分析参数和返回值
3. 生成完整的API文档
4. 包含请求示例、响应示例、错误码

2.2 支持的文档格式

OpenCode支持多种文档格式：

2.3 基础配置

在 opencode.json中配置文档生成：

{"documentation": {"autoGenerate": true,"format": "markdown","includeExamples": true,"includeErrors": true  }}

三、实战：生成API文档

3.1 场景一：生成REST API文档

# 为Spring Boot项目生成API文档> 分析 src 目录下的 Controller，生成完整的REST API文档

AI会生成这样的文档：

## 用户接口### 获取用户信息**接口地址**: `GET /api/users/{id}`**请求参数**:| 参数名 | 类型 | 必填 | 说明 ||-------|------|-----|------|| id | Long | 是 | 用户ID || include | String | 否 | 额外返回字段，可选值：roles,permissions,orders |**返回示例**:```json{  "code": 200,  "data": {    "id": 1,    "name": "张三",    "email": "zhangsan@example.com"  },  "message": "success"}

错误码:

### 3.2 场景二：更新现有文档代码改了，文档也要同步更新：```bash# 更新文档> 分析新增的接口，更新 docs/api.md# 或者> 对比代码和文档，找出不一致的地方

3.3 场景三：生成多种格式

# 生成Markdown文档> 为这个项目生成README.md，包含项目说明、接口列表、安装说明# 生成Swagger/OpenAPI规范> 生成 openapi.yaml 文件# 生成JSDoc注释> 为所有未文档化的函数添加JSDoc注释

四、代码即文档：注释自动生成

4.1 JSDoc自动生成

JavaScript/TypeScript项目：

# 为所有函数添加注释> 为 src 目录下的所有 TypeScript 文件生成 JSDoc 注释

AI会生成这样的注释：

/** * 获取用户信息 *  * @async * @param {number} id - 用户ID * @param {string} [include] - 额外返回字段，用逗号分隔 * @returns {Promise<User>} 用户信息 * @throws {Error} 用户不存在 *  * @example * const user = await getUserById(1); * const userWithDetails = await getUserById(1, 'roles,permissions'); */asyncfunctiongetUserById(id: number, include?: string): Promise<User> {// ...}

4.2 Spring Doc集成

Java项目可以用Spring Doc自动生成OpenAPI文档：

# 配置Spring Doc依赖后，AI可以帮助配置> 为这个Spring Boot项目配置SpringDoc OpenAPI，生成API文档

在 pom.xml中添加：

<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.3.0</version></dependency>

访问 http://localhost:8080/swagger-ui.html即可查看。

4.3 自动生成请求示例

# 为每个接口生成curl示例> 生成所有接口的curl请求示例# 输出curl -X GET "http://localhost:8080/api/users/1" \  -H "Authorization: Bearer {token}"

五、文档维护：让AI帮你同步

5.1 定时更新

配合Git hooks，每次提交自动更新文档：

# .git/hooks/pre-commitopencode--generate-docsgitadddocs/

5.2 CI/CD集成

# .github/workflows/docs.ymlname:APIDocson:push:branches:[main]jobs:docs:runs-on:ubuntu-lateststeps:-uses:actions/checkout@v3-name:GenerateDocsrun:|          npm install -g opencode          opencode "generate api documentation"-name:CommitDocsrun:|          git config user.name "CI"          git config user.email "ci@example.com"          git add docs/          git commit -m "chore: update API docs" || exit 0          git push

5.3 文档版本管理

# 生成带版本号的文档> 生成 API v2 文档，放到 docs/v2/# 对比不同版本> 对比 v1 和 v2 文档，找出接口变化

六、避坑指南：文档生成要注意啥

6.1 注释要规范

AI生成文档的质量，取决于你的代码注释：

// ❌ 这样的注释，AI也救不了publicvoidprocess(){// 处理}// ✅ 这样的注释，AI能发挥最大价值/** * 处理用户订单 * @param orderId 订单ID * @return 处理结果 */public ProcessResult process(Long orderId){// 处理订单逻辑}

6.2 类型要明确

// ❌ any是文档杀手functiongetData(id: any): any// ✅ 类型清晰，文档自动生成functiongetData(id: number): Promise<User>

6.3 命名要规范

// ❌ 奇怪的命名publicvoiddoIt(Long id)// ✅ 见名知意publicvoiddeleteUserById(Long userId)

七、进阶技巧：文档生成的高级玩法

7.1 自定义文档模板

# 使用自定义模板> 生成API文档，使用 docs/template.md 作为模板

# {{title}}## 接口列表{{#each endpoints}}### {{method}} {{path}}{{/each}}

7.2 多语言支持

# 生成中英文文档> 生成双语API文档，中文优先，英文翻译# 输出- docs/api.zh.md- docs/api.en.md

7.3 文档站点

# 生成静态文档站点> 用 VitePress 生成文档站点# 自动部署到 GitHub Pages> 构建并发布文档站点到 gh-pages 分支

八、真实案例：我是怎么用起来的

8.1 案例一：新项目初始化

新项目启动，我都会执行：

# 一步到位> 为这个新项目：   1. 生成项目README.md   2. 配置JSDoc注释规范   3. 生成初始API文档模板   4. 配置Git hooks自动更新文档

原来要搞半天的文档工作，5分钟搞定。

8.2 案例二：老文档更新

接手老项目，第一件事就是：

# 扫描现有代码，生成文档> 分析这个项目的所有接口，生成完整的API文档# 对比现有文档> 对比生成的文档和现有 docs/api.md，找出差异

8.3 案例三：接口变更同步

每次接口变更：

# 代码提交时自动检查> 检查本次提交的代码是否有未文档化的接口# 或者定时检查> 每周扫描项目，生成文档变更报告

九、总结：文档真的可以很简单

核心体验：

• 代码即文档：注释写好，文档自动生成
• 一键同步：代码改了，文档跟着变
• 多种格式：Markdown、Swagger、HTML，想要啥有啥
• CI/CD集成：提交代码自动更新文档

我的日常工作流：

1. 写代码时：> 为这个函数添加JSDoc注释
2. 接口完成后：> 生成API文档预览
3. 代码提交时：自动更新文档
4. 发版时：> 生成带版本号的文档

用完OpenCode的文档生成，我只想说：终于可以安心写代码了，再也不用当文档工具人。

参考资料：

• OpenCode 文档生成配置– https://opencode.ai/docs/config/
• 用 OpenCode 构建文档处理管线– https://www.hubwiz.com/blog/build-a-documentation-pipeline-using-opencode/
• 2026年10个最佳API文档工具推荐– https://apifox.com/apiskills/api-docs-tools/
• ASP.NET Core OpenAPI文档生成– https://learn.microsoft.com/zh-cn/aspnet/core/fundamentals/openapi/