OpenAPI领域建模与架构设计 - 第2节

2.1 OpenAPI 规范历史：从 Swagger 到行业标准

OpenAPI 规范（OAS）起源于 2010 年 Swagger 项目，最初由 Reverb Technologies（后更名为 SmartBear Software）的 Tony Tam 创建，旨在为 RESTful API 提供一种机器可读的描述格式。2015 年，SmartBear 将 Swagger 规范捐赠给 Linux 基金会下的 OpenAPI Initiative（OAI），规范正式更名为 OpenAPI Specification。

2.2 OpenAPI 核心作用：API 契约的单一事实来源

OpenAPI 规范的核心价值在于为 API 提供一份机器可读、人类可读、工具可处理的契约描述。这份契约贯穿 API 的整个生命周期，从设计、开发、测试到文档生成和客户端 SDK 生成。

2.2.1 三大核心能力

• 标准化描述：统一使用 YAML 或 JSON 格式描述端点、请求/响应结构、参数、认证方式、错误码等。
• 自动化工具链：基于规范文件可自动生成交互式文档（如 Swagger UI）、服务端桩代码、客户端 SDK、测试用例。
• 跨团队协作：前后端、QA、产品、第三方开发者共享同一份契约，减少沟通歧义。

2.2.2 典型应用场景

2.3 OpenAPI 与 API First 设计理念

API First（API 优先）是一种软件设计方法论，强调在编写任何实现代码之前，先设计并定义 API 契约。OpenAPI 规范是 API First 理念最核心的技术载体。

2.3.1 API First 的核心原则

1. 契约先行：在开发前完成 API 规范设计，作为团队共识的“合同”。
2. 设计驱动开发：API 设计决定系统边界和交互方式，实现代码遵循设计。
3. 持续验证：通过契约测试确保实现与设计始终一致。
4. 文档即产品：API 文档不是事后补充，而是与设计同步产出的第一份交付物。

2.3.2 传统开发 vs API First 开发

2.3.3 API First 工作流中的 OpenAPI 角色

2.3.4 领域边界与 OpenAPI 的映射关系

在领域驱动设计中，每个限界上下文（Bounded Context）通常对应一个或多个 OpenAPI 描述文件。API 的端点、资源模型、错误码等元素直接反映领域概念和业务规则。

# 示例：订单限界上下文的 OpenAPI 片段
openapi: 3.0.3
info:
  title: 订单服务 API
  version: 1.0.0
  description: 属于“订单”限界上下文，负责订单创建、支付、退款
paths:
  /orders:
    post:
      summary: 创建订单
      operationId: createOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        '201':
          description: 订单创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
components:
  schemas:
    Order:
      type: object
      properties:
        orderId:
          type: string
          description: 订单唯一标识（聚合根 ID）
        status:
          type: string
          enum: [pending, paid, shipped, cancelled]
        totalAmount:
          type: number
          format: decimal