1. OpenAPI 契约基础
1.1 OpenAPI 规范简介
OpenAPI 规范（原 Swagger 规范）是用于描述 HTTP API 的接口描述语言，采用 JSON 或 YAML 格式编写。它定义了一套标准化的元数据结构，使人类和机器都能理解 API 的能力、输入参数、响应格式、认证方式等核心要素。
核心版本演进： OpenAPI 2.0（Swagger 2.0）→ OpenAPI 3.0（引入 server、components、securitySchemes 重构）→ OpenAPI 3.1（兼容 JSON Schema 2020-12，支持描述 WebSocket 和 Webhook）。
| 规范要素 | 说明 | 示例字段 |
|---|---|---|
| openapi | 规范版本号 | 3.0.3 |
| info | API 元信息 | title, version, description |
| servers | 服务端点列表 | url, description |
| paths | 路径与操作 | get, post, parameters |
| components | 可复用组件 | schemas, responses, parameters |
| security | 全局安全策略 | bearerAuth, apiKey |
openapi: "3.0.3"
info:
title: 用户服务 API
version: "1.0.0"
description: 提供用户注册、登录、信息查询能力
servers:
- url: https://api.example.com/v1
paths:
/users/{userId}:
get:
summary: 获取用户信息
parameters:
- name: userId
in: path
required: true
schema:
type: string
responses:
"200":
description: 成功返回用户对象
content:
application/json:
schema:
$ref: "#/components/schemas/User"
components:
schemas:
User:
type: object
properties:
id:
type: string
name:
type: string
email:
type: string
1.2 契约驱动开发理念
契约驱动开发（Contract-First Development）将 API 契约作为团队协作的“第一公民”。在编写任何实现代码之前，先由前后端、平台、测试团队共同定义并评审 OpenAPI 契约文件，再基于契约并行开发。
关键原则： 契约即真相来源（Source of Truth）。所有客户端、服务端、网关、文档、测试用例都从同一份 OpenAPI 文件生成或校验，消除信息不对称。
- 先契约，后实现 — 团队围绕 YAML/JSON 契约讨论接口语义，而非口头约定或文档截图。
- 契约即文档 — 通过 Swagger UI、Redoc 等工具自动生成交互式文档，保持文档与实现同步。
- 契约即测试 — 使用 Dredd、Schemathesis 等工具对实现进行契约合规性测试，确保不偏离约定。
- 契约即模拟 — 基于契约生成 Mock Server，前端可在后端未完成时独立开发调试。