全栈开发助手：OpenClaw+千问3.5-9B自动生成API文档

1. 为什么我们需要自动化API文档生成

作为全栈开发者，我经常陷入这样的困境：后端代码写完了，前端同事却还在等API文档。手动维护Swagger文档不仅耗时，还容易因代码变更导致文档过期。更糟的是，当接口参数调整时，如果忘记更新文档，前端调用就会报错——这种前后端"扯皮"消耗了我们大量沟通成本。

直到我发现OpenClaw+千问3.5-9B的组合可以自动化这个过程。这个方案的核心价值在于：

• 代码即文档：直接从代码注释生成规范文档，避免"文档滞后于代码"
• 智能转换：千问3.5-9B能理解复杂的代码逻辑，将其转化为符合OpenAPI规范的描述
• 一键部署：生成的文档可直接推送到测试环境，与Postman无缝联动

2. 环境准备与基础配置

2.1 安装OpenClaw与模型服务

我选择在本地MacBook Pro上部署这套方案。首先通过官方脚本安装OpenClaw：

curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon

在配置向导中选择Advanced模式，将模型提供商设置为Qwen。关键步骤是指定千问3.5-9B的本地服务地址。我的模型部署在另一台服务器的8000端口，因此在~/.openclaw/openclaw.json中添加：

{
  "models": {
    "providers": {
      "qwen-local": {
        "baseUrl": "http://192.168.1.100:8000/v1",
        "api": "openai-completions",
        "models": [
          {
            "id": "qwen3-9b",
            "name": "Qwen-3.5-9B-Local",
            "contextWindow": 32768
          }
        ]
      }
    }
  }
}

配置完成后，启动网关服务：

openclaw gateway start

2.2 安装API文档生成技能

OpenClaw的扩展能力通过Skill实现。我们需要安装专门处理API文档的skill：

clawhub install api-doc-generator

这个skill提供了三个核心能力：

1. 解析代码中的注释块（支持Java/Python/Go等主流语言）
2. 将注释转换为自然语言描述
3. 生成符合Swagger/OpenAPI 3.0规范的YAML文件

3. 从代码到文档的自动化流水线

3.1 注释解析与增强

我的Spring Boot项目中有这样一个Controller：

/**
 * 用户管理模块
 * @author dev
 */
@RestController
@RequestMapping("/api/user")
public class UserController {
    
    /**
     * 创建新用户
     * @param userDTO 用户数据
     * @return 创建结果
     */
    @PostMapping
    public Result<UserVO> createUser(@RequestBody @Valid UserDTO userDTO) {
        // 实现逻辑...
    }
}

通过OpenClaw执行以下命令：

openclaw run api-doc-generator \
  --input ./src/main/java/com/example/controller \
  --output ./api-spec \
  --format openapi3

这个过程会：

1. 扫描所有Java文件提取注释
2. 将代码结构发送给千问3.5-9B进行语义分析
3. 生成增强版的API描述（包括参数示例、错误码等）

3.2 生成Swagger规范

千问3.5-9B生成的OpenAPI规范片段如下：

paths:
  /api/user:
    post:
      tags: [用户管理]
      summary: 创建新用户
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserDTO'
      responses:
        '200':
          description: 创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
components:
  schemas:
    UserDTO:
      type: object
      properties:
        username:
          type: string
          example: "user123"
          description: 用户名(4-20位字母数字)
        password:
          type: string
          format: password
          minLength: 8

相比原始注释，生成的规范包含了更丰富的元数据：

• 参数格式验证规则
• 示例值
• 响应数据结构
• 错误处理约定

4. 文档部署与测试联动

4.1 自动部署到测试环境

OpenClaw可以进一步将生成的文档部署到Swagger UI。我配置了一个简单的GitHub Actions工作流：

name: Deploy API Docs
on:
  push:
    paths:
      - 'api-spec/**'
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: |
          docker run -d -p 8080:8080 \
            -v $(pwd)/api-spec:/usr/share/nginx/html/swagger \
            swaggerapi/swagger-ui

当API规范文件变更时，会自动更新Swagger UI服务。团队其他成员随时可以访问http://our-test-env:8080查看最新文档。

4.2 与Postman的深度集成

更实用的是与Postman的联动。通过OpenClaw的postman-collection技能，可以直接生成Postman集合：

openclaw run postman-collection \
  --input ./api-spec/openapi.yaml \
  --output ./postman/collection.json

生成的集合包含：

• 所有接口的请求示例
• 环境变量模板
• 测试用例骨架
• 认证配置

前端开发者导入这个集合后，可以直接开始调试，无需手动配置每个请求。

5. 实际效果与优化建议

这套方案在我们团队运行一个月后，API相关的沟通问题减少了约70%。有几个特别实用的场景：

• 接口变更通知：当后端修改参数后，文档自动更新，Postman集合版本会通过飞书机器人通知前端
• Mock服务：利用生成的OpenAPI规范快速创建Mock API，前端不依赖后端进度
• 自动化测试：基于规范生成的测试用例可以作为契约测试的基础

过程中也遇到一些需要优化的点：

1. 复杂泛型参数的描述有时不够准确，需要手动补充说明
2. 大代码库的解析耗时较长（约2分钟扫描500个Java文件）
3. 需要规范团队的注释书写风格

我的改进方法是创建了一个.clawignore文件，排除测试代码和非核心模块：

**/test/**
**/example/**
**/config/**

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。