openapi-specification-v3.2

OpenAPI Specification 3.2

面向 Agent 的 OpenAPI Specification 3.2.0 参考。适用于编辑、生成或验证 OpenAPI 描述（OAD）时。

何时使用

• 编写或更新 OpenAPI 3.2 YAML/JSON 文档
• 解析多文档 OAD 中的 $ref、$self 和相对 URI
• 描述路径、操作、参数（query/path/header/cookie/querystring）、请求体和响应
• 使用 Schema Object（JSON Schema Draft 2020-12 方言）、components 和引用
• 配置安全方案（apiKey、http、mutualTLS、oauth2、openIdConnect）和要求
• 处理媒体类型、编码（form、multipart）和示例（dataValue/serializedValue/externalValue）

核心参考

主题	描述	参考
OpenAPI 对象	根对象、openapi、$self、info、servers、paths、webhooks、components、security、tags	core-openapi-object
格式与结构	JSON/YAML、大小写敏感、富文本、OAD 结构、解析、基础 URI	core-format-and-structure
固定字段与模式字段	固定字段与模式字段、paths 键、components 键、扩展（x-）	core-fixed-patterned-fields
信息与元数据	Info、Contact、License 对象	core-info-metadata
服务	Server 对象、Server Variable、URL 模板化	core-server
路径与操作	Paths 对象、Path Item、Operation 对象、additionalOperations、query	paths-and-operations
路径模板化	路径模板化、路径参数、匹配、ABNF	core-path-templating
参数	Parameter 对象、in（path/query/header/cookie/querystring）、style、schema 与 content	parameters
请求体与媒体类型	Request Body、Media Type 对象、顺序媒体类型、itemSchema	request-body-and-media-type
编码对象	按名称/位置编码、contentType、style、explode、form、multipart	core-encoding-object
媒体类型	Content 键、媒体类型范围、OpenAPI Media Type Registry	core-media-types
响应	Responses 对象、Response 对象、headers、content、links	responses
HTTP 状态码	Response 键、default、1XX–5XX 范围与 X	core-http-status-codes
Schema 与 Components	Schema 对象（JSON Schema 2020-12）、Components、$ref 解析	schema-and-components
Schema JSON Schema 关键字	Schema 中的 JSON Schema 2020-12 关键字与 OAS 扩展	schema-json-schema-keywords
Schema 组合与多态	allOf、oneOf、anyOf、discriminator	schema-composition-polymorphism
数据类型与格式	JSON Schema 类型、format 关键字、OAS 方言	core-data-types-and-formats
Discriminator 与 XML	Discriminator 对象、XML 对象（nodeType、name、namespace）	core-discriminator-and-xml
Components 复用	通过 $ref 复用参数、响应、schema	components-reuse
Reference 对象	$ref、summary/description 覆盖、解析规则	core-reference-object
Header 对象	响应/multipart 头、style simple、Set-Cookie、Link	core-header-object
Example 对象	dataValue、serializedValue、value、externalValue、Working with Examples	core-example-object
Tag 与外部文档	Tag 对象、External Documentation 对象、parent、kind	core-tags-and-external-docs
Link 对象	operationRef、operationId、parameters、requestBody	core-link-object
运行时表达式	$request、$response、$url、$method、ABNF、Link/Callback 用法	core-runtime-expressions
安全	Security Scheme、OAuth Flows、Security Requirement 对象	security
安全方案类型	apiKey、http（basic/bearer）、mutualTLS、oauth2、openIdConnect	security-scheme-types
Security Requirement 对象	OR/AND 语义、{} 可选、[] 清除、scopes	security-requirement-object
OAuth2 流程	OAuth Flows 对象、OAuth Flow 对象、authorizationCode、deviceAuthorization	security-oauth2-flows
回调与 Webhooks	Callback 对象、webhooks	callbacks-and-webhooks
扩展	规范扩展（x-）、扩展注册表	advanced-extensions

最佳实践

主题	描述	参考
规范编写	operationId、tags、$self、components 复用、responses、security	best-practices-spec-authoring

进阶

主题	描述	参考
基础 URI 与解析	$self、检索 URI、引用解析、解析指南	advanced-base-uri-and-resolution
安全过滤	空 Paths/Path Item、安全注意事项	advanced-security-filtering

要点

• OAS 3.2 根对象使用 openapi: 3.2.0；components、paths 或 webhooks 中至少有一个必须存在。
• $self 提供文档用于引用解析的基础 URI；在多文档 OAD 中使用它。
• Schema Object 是 JSON Schema Draft 2020-12 的超集；空 schema = true，无 schema = false。
• Parameter：使用 schema+style 或 content（一种 Media Type）；in: "querystring" 需要 content。
• 根级别的 security 为 OR（Security Requirement Object 之一）；每个操作可覆盖；{} = 可选。