2. OpenAPI 规范基础：规范简介、版本演进与核心文件结构
OpenAPI 规范（原名 Swagger 规范）是业界标准的、语言无关的 RESTful API 接口描述格式。它允许开发者使用 JSON 或 YAML 文件定义 API 的端点、请求参数、响应结构、认证方式以及错误码等元数据。在本课程中，OpenAPI 文档将作为“错误码断言通信机制”的契约基础，因此理解其核心结构至关重要。
2.1 OpenAPI 规范简介
OpenAPI 规范由 Linux 基金会旗下的 OpenAPI Initiative（OAI）维护，旨在建立一种机器可读、人类可读的 API 契约标准。其核心价值在于：
- 契约驱动开发：前后端、微服务之间基于同一份文档进行开发，减少联调冲突。
- 自动化工具链：支持自动生成客户端 SDK、服务端桩代码、API 文档门户以及测试用例。
- 错误码标准化：通过
components/responses和schema定义统一的错误响应结构，为断言验证提供精确的匹配依据。
课程关联： 本课程后续章节将利用 OpenAPI 文档中的
responses 和 schemas 定义，自动提取“预期错误码”与“预期响应体结构”，并与实际 HTTP 响应进行断言比对。
2.2 版本演进与关键差异
OpenAPI 规范经历了从 Swagger 2.0 到 OpenAPI 3.0 的重大演进。当前主流版本为 3.0.x 和 3.1.x。下表列出了核心差异：
| 特性 | Swagger 2.0 | OpenAPI 3.0.x | OpenAPI 3.1.x |
|---|---|---|---|
| 根字段 | swagger: '2.0' |
openapi: '3.0.0' |
openapi: '3.1.0' |
| 请求体描述 | body 参数 + formData |
requestBody 对象（统一且更灵活） |
继承 3.0，支持 JSON Schema 2020-12 |
| 响应描述 | responses 直接内联 |
responses 支持引用 components/responses |
继承 3.0，增强类型安全 |
| 多态/组合 | 有限支持 | oneOf / anyOf / allOf |
完全兼容 JSON Schema 组合关键字 |
| 示例 | examples 字段 |
example 单值 + examples 多值 |
继承 3.0，增强媒体类型示例 |
| 路径参数 | 需在 parameters 中显式声明 |
支持路径模板自动解析 | 继承 3.0 |
版本选择建议： 本课程所有示例基于 OpenAPI 3.0.3。该版本在工具链兼容性和 JSON Schema 支持之间取得了最佳平衡，且被主流 API 网关和测试框架广泛支持。
2.3 核心文件结构
一个标准的 OpenAPI 文档由四个顶级对象构成：openapi、info、paths 和 components。下图展示了它们之间的层级关系：
2.4 核心字段详解
2.4.1 openapi 与 info
openapi 字段声明规范版本，info 提供 API 的元数据。示例：
openapi: '3.0.3'
info:
title: 用户管理 API
version: '1.0.0'
description: 提供用户注册、登录、信息查询接口，包含标准化错误码响应。
2.4.2 paths：API 端点与错误码定义
paths 是文档的核心，定义了每个端点（如 /users）支持的 HTTP 方法及其响应。每个响应必须包含一个 HTTP 状态码（如 200、400、500），这是错误码断言的基础。
paths:
/users:
get:
summary: 获取用户列表
responses:
'200':
description: 成功返回用户列表
content:
application/json:
schema:
$ref: '#/components/schemas/UserList'
'400':
description: 请求参数错误
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: 服务器内部错误
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
断言关键点： 测试框架将遍历
paths 下的每个 responses 状态码（如 400、500），提取对应的 schema 结构，作为“预期错误响应”与真实 HTTP 响应进行字段级断言。
2.4.3 components：可复用错误码组件
components 用于定义可复用的 schemas（数据结构）和 responses（完整响应模板）。这是实现错误码标准化的关键机制。
components:
schemas:
ErrorResponse:
type: object
properties:
code:
type: string
description: 业务错误码，如 'USER_NOT_FOUND'
message:
type: string
description: 人类可读的错误描述
requestId:
type: string
description: 用于追踪的请求唯一标识
required:
- code
- message
responses:
BadRequest:
description: 请求参数校验失败
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
InternalServerError:
description: 服务器内部错误
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
2.5 错误码断言通信机制中的 OpenAPI 角色
下图展示了 OpenAPI 文档如何驱动错误码断言验证流程：
2.6 本章小结
- OpenAPI 规范 是 API 契约的标准语言，版本 3.0.3 是本课程的基础。
- 核心结构 包括
openapi、info、paths和components，其中paths定义端点与错误码，components定义可复用的错误响应模板。 - 错误码断言 依赖于从
paths/responses中提取的 HTTP 状态码和从components/schemas中提取的响应体结构。 - 下一章将深入讲解如何编写符合本课程需求的 OpenAPI 文档，重点聚焦于错误码组件的设计模式。