用 AI 实现你的 OpenAPI

Posted on Mon 27 October 2025 in Journal

Abstract 用 AI 实现你的 OpenAPI
Authors Walter Fan
 Category    learning note  
Status v1.0
Updated 2025-10-27
License CC-BY-NC-ND 4.0

用 OpenAPI 来定义你的 API

关键词：OpenAPI、Swagger、API 文档、活文档、文档驱动编程、AI 辅助编程

一、OpenAPI 是什么？

一句话概括：

OpenAPI 是用来描述 RESTful API 的标准格式。

它不是一个框架，也不是一个库， 而是一个文档规范（Specification）—— 类似于接口的“蓝图”或“契约（Contract）”。

就像 C/C++ 里的头文件 .h，或者 Java 里的接口 interface， OpenAPI 描述了：

  • API 提供哪些路径（endpoints）
  • 每个路径支持哪些 HTTP 方法（GET、POST、PUT、DELETE）
  • 参数、请求体、返回值长什么样
  • 返回码、错误格式等

让 人 和 机器 都能理解你的接口。

二、一个简单例子

比如你有个用户服务：

GET /api/users/{id}

返回用户信息。

你可以用 OpenAPI（YAML 格式）这样描述它：

openapi: 3.0.3
info:
  title: 用户服务 API
  version: 1.0.0
paths:
  /api/users/{id}:
    get:
      summary: 获取指定用户信息
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 成功返回用户信息
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string

这就是一份合法的 OpenAPI 文档。

三、它能做什么？

这份文档不是摆设。 有了它，你可以做很多事：

用途 说明
✅ 生成 API 文档 自动生成漂亮的网页文档（Swagger UI、Redoc）
✅ 生成客户端 SDK 一键生成 Java、Go、Python、TypeScript 的 API 调用代码
✅ 生成服务端骨架 一键生成控制器、路由模板
✅ 校验请求/响应 自动验证参数、类型、格式是否符合定义
✅ Mock 服务 没有后端也能跑接口联调测试

这就是为什么很多团队在 CI/CD 里都加上了 OpenAPI 检查： 接口变更前先改 OpenAPI 文件，再生成代码或文档。

四、和 Swagger 的关系

很多人一开始以为 “Swagger = OpenAPI”，其实：

名称 作用
OpenAPI Specification (OAS) 规范标准（由 Linux Foundation 管理）
Swagger 一系列基于 OpenAPI 的工具（由 SmartBear 公司维护）
Swagger UI / Editor / Codegen 实现 OpenAPI 的可视化与代码生成工具

所以：

  • 规范：OpenAPI
  • 工具：Swagger

五、语言生态（针对你熟悉的几门语言）

语言 常见框架 OpenAPI 工具
Java Spring Boot Springdoc OpenAPI（推荐）、Swagger-Core
Go Gin / Echo / Fiber swaggo/swag、go-openapi、oapi-codegen
Python FastAPI、Flask FastAPI 原生支持、flasgger
C++ Pistache、Restbed OpenAPI Generator 生成代码骨架

举个 Java 的例子：

@RestController
@RequestMapping("/api/users")
@Tag(name = "用户管理")
public class UserController {

    @Operation(summary = "根据ID获取用户信息")
    @GetMapping("/{id}")
    public User getUser(@PathVariable Long id) {
        return new User(id, "Alice", "alice@example.com");
    }
}

配合 springdoc-openapi，你可以自动生成：

  • /v3/api-docs（JSON 格式）
  • /swagger-ui.html（网页文档）

六、版本与演进

版本 时间 特点
OpenAPI 2.0 以前叫 Swagger 2.0 JSON/YAML 支持
OpenAPI 3.0 主流版本 增强请求体定义
OpenAPI 3.1 最新 完全支持 JSON Schema 2020-12

建议现在用 3.0+。

七、OpenAPI 与活文档（Living Documentation）

什么是活文档？

传统 API 文档最大的问题是什么？容易过时。

今天改了接口，明天忘记更新文档；文档和代码不一致，导致前后端对接时频频出错。这是很多团队的痛点。

活文档（Living Documentation） 的理念是：让文档成为代码的一部分，随代码自动更新。

OpenAPI 如何实现活文档？

OpenAPI 通过以下方式实现活文档：

1. 代码即文档（Code as Documentation）

通过注解或装饰器，让文档定义直接写在代码里：

@Operation(summary = "创建用户", description = "创建一个新用户账户")
@PostMapping("/users")
public ResponseEntity<User> createUser(
    @RequestBody @Valid UserCreateRequest request
) {
    // 实现代码
}

当代码变更时，OpenAPI 文档自动更新。

2. 文档驱动开发（Documentation-Driven Development）

另一种方式是先写文档，再写代码：

  1. 在 openapi.yaml 中定义接口规范
  2. 使用工具生成服务端骨架代码
  3. 实现业务逻辑
  4. 运行时验证请求/响应是否符合文档

这样文档永远是"最新版本"，因为它就是唯一的真实来源（Single Source of Truth）。

3. 持续验证

在 CI/CD 流程中加入文档校验：

# .github/workflows/api-docs.yml
- name: Validate OpenAPI
  run: |
    npx @stoplight/spectral-cli lint openapi.yaml

- name: Generate SDK
  run: |
    openapi-generator generate -i openapi.yaml -g typescript-axios

- name: Test against spec
  run: |
    npm run test:api-contract

每次代码提交，都会验证文档与实现的一致性。

活文档的价值

传统文档 活文档
手动维护，容易过时 自动生成，始终同步
静态 HTML/PDF，无法交互 交互式 UI，可直接测试接口
仅面向人类阅读 机器可读，可生成代码、进行验证
需要额外工具链 集成在开发流程中

活文档让文档从"负担"变成"资产"。

八、文档驱动编程与 AI 辅助编程

文档驱动编程的核心思想

文档驱动编程（Documentation-Driven Development, DDD） 的核心是：

文档不是开发的副产品，而是开发的起点和契约。

先定义"做什么"（What），再实现"怎么做"（How）。

这与契约驱动开发（Contract-Driven Development） 一脉相承：

OpenAPI 文档 = API 契约
     ↓
代码实现 = 契约的实现
     ↓
自动验证 = 确保实现符合契约

AI 辅助编程时代的机遇

在 AI 辅助编程（如 GitHub Copilot、Cursor、Claude 等）的时代，结构化文档的价值被放大：

1. AI 能够理解 OpenAPI 规范

现代 AI 模型经过大量代码和文档训练，对 OpenAPI 规范非常熟悉。当你提供 OpenAPI 文档时，AI 可以：

场景一：根据文档生成代码

你：根据这个 OpenAPI 文档，生成 Spring Boot Controller

AI：分析 openapi.yaml → 生成完整的 Controller 代码

# openapi.yaml
paths:
  /api/users/{id}:
    get:
      summary: 获取用户信息
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

AI 可以据此生成：

@RestController
@RequestMapping("/api/users")
public class UserController {

    @GetMapping("/{id}")
    public ResponseEntity<User> getUser(@PathVariable Integer id) {
        // AI 生成的代码骨架
    }
}

场景二：根据文档生成测试用例

你：为这个 API 生成完整的测试用例

AI：分析文档 → 生成单元测试、集成测试、契约测试

场景三：文档补全与优化

你：检查这个 OpenAPI 文档是否完整，补充缺失的部分

AI：分析现有文档 → 发现缺失字段 → 提供建议和补全

2. AI 作为"文档翻译器"

AI 可以在不同抽象层次之间转换：

自然语言需求
    ↓ (AI 理解)
OpenAPI 文档
    ↓ (AI 生成)
代码实现
    ↓ (AI 验证)
测试用例

实际工作流示例：

开发者：我需要一个用户注册接口，接收邮箱和密码，返回用户ID和token

AI（分析需求）：
→ 生成 OpenAPI 文档片段
→ 生成 Controller 代码
→ 生成 Service 层代码
→ 生成 DTO 类
→ 生成测试用例
→ 生成 API 文档页面

3. AI 辅助的文档审查

AI 可以帮助审查 OpenAPI 文档的质量：

  • 一致性检查：字段命名是否统一？状态码使用是否规范？
  • 完整性检查：是否所有端点都有描述？错误响应是否定义？
  • 最佳实践：是否符合 RESTful 设计原则？版本控制是否合理？

实践建议：构建 AI 友好的 API 文档

要让 AI 更好地理解和使用你的 OpenAPI 文档，建议：

✅ 1. 添加详细的描述

paths:
  /api/users/{id}:
    get:
      summary: 获取用户信息
      description: |
        根据用户ID获取用户详细信息。
        如果用户不存在，返回 404。
        需要 Bearer Token 认证。
      operationId: getUserById  # 给 AI 一个明确的标识

✅ 2. 使用示例（Examples）

responses:
  '200':
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/User'
        examples:
          success:
            value:
              id: 1
              name: "Alice"
              email: "alice@example.com"

示例让 AI 更好地理解数据结构。

✅ 3. 明确的错误定义

responses:
  '400':
    description: 请求参数错误
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/Error'
  '404':
    description: 用户不存在
  '500':
    description: 服务器内部错误

✅ 4. 使用语义化的 schema 名称

components:
  schemas:
    User:           # ✅ 好：语义清晰
      type: object
    UserResponse:   # ✅ 好：明确是响应对象
    UserCreateRequest:  # ✅ 好：明确是请求对象

而不是：

components:
  schemas:
    User1:          # ❌ 差：无意义
    Data:           # ❌ 差：太泛化

AI 辅助编程的未来展望

随着 AI 能力的提升，文档驱动编程 + AI 辅助编程的组合将会：

  1. 降低 API 设计门槛：非技术人员也能通过自然语言描述生成 API 文档
  2. 加速开发迭代：从文档到代码的转换时间大幅缩短
  3. 提升代码质量：AI 根据文档生成代码，天然保证接口一致性
  4. 自动化测试生成：AI 根据 OpenAPI 文档自动生成全面的测试用例

九、实践建议（经验谈）

对老程序员来说，最重要的不是学语法，而是掌握 使用流程：

  1. 先定义 OpenAPI 文档（可手写或用 Swagger Editor，或让 AI 帮你生成）
  2. 让后端代码实现它（生成接口骨架或校验，或让 AI 根据文档生成代码）
  3. 让前端或测试通过文档调用（生成 SDK 或 Mock 服务）
  4. 持续集成里验证文档是否同步（自动化检查）

在 AI 时代，这个流程更加顺畅：

需求 → AI 生成 OpenAPI 文档 → AI 生成代码骨架 → 人工实现业务逻辑 → AI 生成测试 → 自动化验证

长期坚持下来，你的项目会非常规范：

  • 接口变更有据可查
  • 前后端解耦
  • SDK、测试、Mock 一键生成
  • AI 辅助开发效率大幅提升

十、小结

OpenAPI = Web 接口的"IDL"（接口定义语言）。 它让 REST API 变得像 gRPC、Thrift 一样可描述、可生成、可验证。

更重要的是，在 AI 辅助编程的时代：

OpenAPI + 活文档 + AI = 高效的 API 开发范式

文档不仅是给人看的，更是给机器（包括 AI）读的。 一份好的 OpenAPI 文档，是 AI 理解你的接口、生成代码、进行测试的"知识图谱"。

本作品采用知识共享署名-非商业性使用-禁止演绎 4.0 国际许可协议进行许可。

journal blog

Previous Post Next Post

You might enjoy