OpenAPI规范。

一、OpenAPI规范是什么

OpenAPI 规范（OAS）是一种和编程语言无关的接口描述标准，用于定义 HTTP API（以 REST 风格为主）。在不访问源码的情况下使用服务的功能。作用包括：生成交互式文档、生成客户端和服务端代码、做自动化测试以及服务模拟等。

当前主流版本是 3.0.3，最新版本是 3.1.0，和旧的 2.0 版本（Swagger）有显著不同。

二、根文档结构

一个完整的 OpenAPI 文档本身是一个JSON或YAML对象包含几个字段：

openapi

必填，字符串。标明该文档使用的 OpenAPI 规范版本，如 "3.1.0"。

info

必填，提供 API 的元数据。

jsonSchemaDialect

仅在 3.1 中出现，可选字符串，用于声明 Schema Object 所使用的 JSON Schema 方言，默认是 https://spec.openapis.org/oas/3.1/dialect/base。

servers

数组，每个元素是一个 Server Object，至少包含一个 url，表示 API 的基础地址。还可以包含 description 和变量（用于替换 URL 中的模板部分）。

paths

必填，Path Item Object 的集合。文档的重要部分，用于描述 API 的各个端点和操作。

webhooks

在3.1中引入，可选，结构同paths，用于描述API自身主动发出的回调请求（而不再局限于之前 callbacks 的局部定义方式）。

components

可选，存放可重用对象的工具箱，比如 schema、参数、响应等，避免在文档中重复定义。

security

可选，声明全局的安全方案，是一个 Security Requirement Object 数组。如果某操作没有单独指定 security，就会继承这里。

tags

可选数组，定义全局标签，可用于在文档中对操作分组，每个 Tag Object 有 name 和可选的 description、externalDocs。

externalDocs

可选，链接到外部文档。

三、Info 对象（info）

提供 API 的识别信息，必须包含 title 和 version。

title：API 的名称，必填。

version：API 的版本字符串，必填（注意这不是 openapi 版本，而是你自己的 API 版本）。

description：详细描述，支持 Markdown。

termsOfService：服务条款的 URL。

contact：联系人信息，包含 name、url、email。

license：许可证信息，包含 name（必填）、identifier（SPDX 许可证标识，3.1 支持）、url。

四、Server 对象（servers）

用于指定 API 的基础访问地址，支持多服务器（如开发环境、测试环境、生产环境）。

url：必填字符串，如 "https://api.example.com/v1"，可以使用变量占位符 {variable}。

description：服务器的说明文字。

variables：一个对象，键是变量名，值是 Server Variable Object，包含：

default：必填，默认值。

enum：可选，允许的值列表。

description：变量说明。

通过 servers，客户端可以轻松切换环境。

五、途径和操作（paths）

paths 是一个对象，键是相对途径字符串（如 /users、/users/{userId}），值是一个 Path Item Object。

Path Item Object 的字段

每个途径下可以定义如果干操作，标准字段是 HTTP 方法：get、put、post、delete、options、head、patch、trace。此外还包含：

summary：简短摘要。

description：详细说明。

parameters：该途径下所有操作共享的参数列表。

servers：可以包括全局 servers，仅对这个途径生效。

每个操作对象（如 get 对应的对象）除了上述摘要、描述外，还包含：

operationId：用于标识该操作的唯一字符串，建议用动名短语。

parameters：此操作专属的参数。

requestBody：请求体定义，仅适用于 POST、PUT、PATCH 等有请求体的方法。

responses：必填，定义所有可能的响应状态码及其内容。

deprecated：布尔值，标明该操作是不是已弃用。

security：可包括全局安全设置。

callbacks：定义该操作完成后 API 可能发起的回调请求（3.1 新增 webhooks 可集中管理）。

servers：可包括途径或全局服务器。

tags：用来分组。

参数对象（Parameter Object）

既可在途径层级，也可在操作层级定义，描述请求中的参数。重要字段：

name：参数名。

in：必填，参数位置，可选值有：

query：查询参数，如 /items?color=red

header：请求头

path：途径中的模板参数，如 /users/{id}

cookie：Cookie 值

description：描述。

required：是不是必需，当 in 为 path 时必为 true。

schema：定义参数值的类型和格式（使用 Schema Object）。

example / examples：示例值。

style、explode 等：控制序列化方式。

请求体对象（Request Body Object）

描述可选的请求体，用于 POST、PUT 等方法。包含：

description：描述。

required：是不是必需。

content：必填，一个媒体类型到 Media Type Object 的映射。常见的键是 application/json、multipart/form-data 等。每个Media Type Object中必须包含schema（定义结构）和可选的example、examples、encoding（用于 multipart 的详细编码控制）。

响应对象（Responses Object）

responses 是操作下的必填对象，键是 HTTP 状态码（如 "200"、"404"），也可以使用 "default" 代表其他状态。每个响应值是一个 Response Object，包含：

description：必填，对响应的简短描述。

headers：特定响应头定义，结构和参数类似但无需 in。

content：和请求体中的content结构相同，包含媒体类型和schema。

links：链接到其他操作，实现超媒体驱动。

六、内容和Schema（数据结构）

Media Type Object 中的 schema 使用 Schema Object，它根据 JSON Schema 的扩展子集，用来描述数据的类型、格式、约束等。

Schema Object 的常用字段：

type：数据类型，如 string、number、integer、boolean、array、object。

format：进一步指明格式，如 int32、date-time、email、uri 等。

required：在对象中指定必须包含的属性名列表。

properties：定义对象的属性，每个属性又是一个 Schema Object。

items：定义数组元素的 schema。

enum：枚举值列表。

default、example：默认值或示例。

allOf、oneOf、anyOf：用于组合和继承多个 schema。

nullable：3.0 中声明可为 null，3.1 中直接使用 type: ["string", "null"]。

discriminator：当使用 oneOf、anyOf 时，指定辨别字段，用于多态。

xml：控制 XML 序列化。

externalDocs：外部文档链接。

在 OpenAPI 3.1 中，Schema Object 完全兼容 JSON Schema 2020-12，不再剥离某些字，因此可以直接使用 $defs、const 等。

七、Components对象

components 是避免重复的集中定义区，下面可以包含多种可重用对象：

schemas：可重用的 Schema Object，通过 $ref: "#/components/schemas/名称" 引用。

parameters：可重用的参数定义。

requestBodies：可重用的请求体。

responses：可重用的响应。

headers：可重用的响应头。

examples：可重用的示例。

links：可重用的链接定义。

callbacks：可重用的回调定义。

pathItems：可重用的途径项（仅在 3.1 中更确定，某些工具支持）。

securitySchemes：安全方案定义，见下一节。

使用 $ref 引用时，可以局部包括描述、示例等字段，从而实现自定义。

八、安全定义（security 和 securitySchemes）

components/securitySchemes 下定义可用的安全机制，类型由 type 字段决定，包括：

http：HTTP 身份证实，通过 scheme 字段指定（如 basic、bearer），bearer 可加 bearerFormat（如 JWT）。

apiKey：在 in 中指定位置（header、query、cookie），并给出 name。

oauth2：OAuth 2.0，通过 flows 定义授权流程，每个流程包含 authorizationUrl、tokenUrl、scopes 等。

openIdConnect：使用 OpenID Connect Discovery，给出 openIdConnectUrl。

mutualTLS：仅在 3.1 中，表示双向 TLS。

然后在全局的 security 数组或某个操作的 security 里，通过键引用这些方案，值为空数组或指定所需 scope 的列表。

九、扩展和高级特性

Specification Extensions：任何以 x- 开头的字段都可以作为自定义扩展，工具会忽略，但可以用来携带额外信息。

Links：在响应中定义 link，可以描述怎样从当前响应数据构造另一个操作的请求。

Callbacks：定义服务端主动发起的 HTTP 请求，常用于 Webhook 情形。3.1 新增了顶层的 webhooks 字段来更清晰地描述这类回调。

Discriminator：用于多态，在 schema 中使用 discriminator.propertyName 指定鉴别字段，配合 mapping 映射值到具体 schema。