1. OpenAPI 规范概述

OpenAPI 规范（OAS）是业界标准的、语言无关的 HTTP API 接口描述格式。它允许人类和计算机在不访问源代码、文档或网络流量检查的情况下，发现和理解服务的功能。本章将系统梳理其历史演进、版本差异与核心设计理念。

1.1 历史与版本演进

OpenAPI 规范起源于 2010 年 Swagger 规范，经历了从社区标准到 Linux 基金会项目的转变。下表总结了关键里程碑与版本差异：

1.2 Swagger 2.0 vs OpenAPI 3.0/3.1 关键差异

以下列表梳理了从 Swagger 2.0 升级到 OpenAPI 3.x 时必须理解的核心变化：

• 根对象结构：Swagger 2.0 使用 host + basePath + schemes；OpenAPI 3.x 使用 servers 数组，支持多环境与变量。
• 请求体定义：Swagger 2.0 将 body 参数放在 parameters 列表中；OpenAPI 3.x 引入独立的 requestBody 对象，支持 content 与媒体类型映射。
• 可复用组件：Swagger 2.0 使用 definitions + parameters + responses；OpenAPI 3.x 统一为 components 下的 schemas、parameters、requestBodies、responses、headers、links、callbacks。
• 回调与 Webhook：Swagger 2.0 不支持；OpenAPI 3.0 引入 callbacks；OpenAPI 3.1 将 webhooks 提升为顶级对象。
• JSON Schema 对齐：Swagger 2.0 基于 JSON Schema 草案 4，有大量扩展；OpenAPI 3.1 完全兼容 JSON Schema 2020-12，消除了 nullable、discriminator 等专有扩展。

# Swagger 2.0
parameters:
  - in: body
    name: body
    required: true
    schema:
      $ref: '#/definitions/Pet'

# OpenAPI 3.0
requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/Pet'

1.3 核心设计理念与优势

OpenAPI 规范的设计遵循以下核心理念，这些理念直接决定了其在 API 生命周期管理中的优势：

1. 契约优先（Contract-First）：API 文档是团队与消费者之间的“契约”。先定义 OpenAPI 描述文件，再生成服务端存根与客户端 SDK，确保实现与文档始终同步。
2. 语言无关性：规范使用 YAML/JSON 格式，不绑定任何编程语言或框架。任何语言都可以通过解析器生成对应的客户端或服务端代码。
3. 机器可读与人类可读并存：OpenAPI 文件既可以被 Swagger UI、Redoc 等工具渲染为交互式文档，也可以被 CI/CD 流水线、测试框架、网关配置工具直接消费。
4. 可扩展性：通过 x- 扩展字段，允许组织添加自定义元数据（如内部审计标签、错误码映射、合规等级），而不破坏标准解析器。
5. 工具生态成熟：从设计（Stoplight、Swagger Editor）、文档（Swagger UI、Redoc）、测试（Postman、Dredd）、代码生成（OpenAPI Generator、Swagger Codegen）到网关（Kong、AWS API Gateway），形成完整工具链。

1.4 OpenAPI 规范结构总览

下图展示了 OpenAPI 3.1 规范的核心顶层字段及其关系。该结构是后续章节中定义路径、参数、请求体、响应与错误码的基础。

1.5 为什么选择 OpenAPI 作为接口文档标准

在课程后续章节中，我们将基于 OpenAPI 3.1 构建接口文档、定义安全合规错误码断言。选择 OpenAPI 而非其他方案（如 RAML、API Blueprint、GraphQL SDL）的理由如下：