openapi-specification-v3.2

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenAPI Specification 3.2

Agent-oriented reference for the OpenAPI Specification 3.2.0. Use when editing, generating, or validating OpenAPI descriptions (OAD).

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

When to Use

适用场景

Authoring or updating OpenAPI 3.2 YAML/JSON documents
Resolving
```
$ref
```
,
```
$self
```
, and relative URIs in multi-document OADs
Describing paths, operations, parameters (query/path/header/cookie/querystring), request body, and responses
Using Schema Objects (JSON Schema Draft 2020-12 dialect), components, and references
Configuring security schemes (apiKey, http, mutualTLS, oauth2, openIdConnect) and requirements
Working with media types, encoding (form, multipart), and examples (dataValue/serializedValue/externalValue)

编写或更新OpenAPI 3.2 YAML/JSON文档
解决多文档OAD中的
```
$ref
```
、
```
$self
```
和相对URI问题
描述路径、操作、参数（查询/路径/头部/Cookie/查询字符串）、请求体和响应
使用Schema对象（JSON Schema Draft 2020-12方言）、组件和引用
配置安全方案（apiKey、http、mutualTLS、oauth2、openIdConnect）和安全要求
处理媒体类型、编码（表单、多部分）和示例（dataValue/serializedValue/externalValue）

Core References

核心参考

Topic	Description	Reference
OpenAPI Object	Root object, openapi, $self, info, servers, paths, webhooks, components, security, tags	core-openapi-object
Format & Structure	JSON/YAML, case sensitivity, rich text, OAD structure, parsing, base URI	core-format-and-structure
Fixed & Patterned Fields	Fixed vs patterned fields, paths keys, components keys, extensions (x-)	core-fixed-patterned-fields
Info & Metadata	Info, Contact, License objects	core-info-metadata
Server	Server Object, Server Variable, URL templating	core-server
Paths & Operations	Paths Object, Path Item, Operation Object, additionalOperations, query	paths-and-operations
Path Templating	Path templating, path parameters, matching, ABNF	core-path-templating
Parameters	Parameter Object, in (path/query/header/cookie/querystring), style, schema vs content	parameters
Request Body & Media Type	Request Body, Media Type Object, sequential media types, itemSchema	request-body-and-media-type
Encoding Object	Encoding by name/position, contentType, style, explode, form, multipart	core-encoding-object
Media Types	Content keys, media type ranges, OpenAPI Media Type Registry	core-media-types
Responses	Responses Object, Response Object, headers, content, links	responses
HTTP Status Codes	Response keys, default, 1XX–5XX range with X	core-http-status-codes
Schema & Components	Schema Object (JSON Schema 2020-12), Components, $ref resolution	schema-and-components
Schema JSON Schema Keywords	JSON Schema 2020-12 keywords and OAS extensions in Schema	schema-json-schema-keywords
Schema Composition & Polymorphism	allOf, oneOf, anyOf, discriminator	schema-composition-polymorphism
Data Types & Formats	JSON Schema types, format keyword, OAS dialect	core-data-types-and-formats
Discriminator & XML	Discriminator Object, XML Object (nodeType, name, namespace)	core-discriminator-and-xml
Components Reuse	Reusing parameters, responses, schemas via $ref	components-reuse
Reference Object	$ref, summary/description override, resolution rules	core-reference-object
Header Object	Response/multipart headers, style simple, Set-Cookie, Link	core-header-object
Example Object	dataValue, serializedValue, value, externalValue, Working with Examples	core-example-object
Tag & External Docs	Tag Object, External Documentation Object, parent, kind	core-tags-and-external-docs
Link Object	operationRef, operationId, parameters, requestBody	core-link-object
Runtime Expressions	$request, $response, $url, $method, ABNF, Link/Callback usage	core-runtime-expressions
Security	Security Scheme, OAuth Flows, Security Requirement Object	security
Security Scheme Types	apiKey, http (basic/bearer), mutualTLS, oauth2, openIdConnect	security-scheme-types
Security Requirement Object	OR/AND semantics, {} optional, [] clear, scopes	security-requirement-object
OAuth2 Flows	OAuth Flows Object, OAuth Flow Object, authorizationCode, deviceAuthorization	security-oauth2-flows
Callbacks & Webhooks	Callback Object, webhooks	callbacks-and-webhooks
Extensions	Specification extensions (x-), extension registries	advanced-extensions

主题	描述	参考
OpenAPI对象	根对象、openapi、$self、info、servers、paths、webhooks、components、security、tags	core-openapi-object
格式与结构	JSON/YAML、大小写敏感性、富文本、OAD结构、解析、基础URI	core-format-and-structure
固定与模式字段	固定字段vs模式字段、paths键、components键、扩展（x-）	core-fixed-patterned-fields
信息与元数据	Info、Contact、License对象	core-info-metadata
服务器	Server对象、Server变量、URL模板	core-server
路径与操作	Paths对象、Path Item、Operation对象、additionalOperations、查询	paths-and-operations
路径模板	路径模板、路径参数、匹配规则、ABNF	core-path-templating
参数	Parameter对象、位置（path/query/header/cookie/querystring）、style、schema vs content	parameters
请求体与媒体类型	请求体、Media Type对象、顺序媒体类型、itemSchema	request-body-and-media-type
编码对象	按名称/位置编码、contentType、style、explode、表单、多部分	core-encoding-object
媒体类型	Content键、媒体类型范围、OpenAPI媒体类型注册表	core-media-types
响应	Responses对象、Response对象、headers、content、links	responses
HTTP状态码	响应键、default、1XX–5XX范围（带X）	core-http-status-codes
Schema与组件	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
鉴别器与XML	Discriminator对象、XML对象（nodeType、name、namespace）	core-discriminator-and-xml
组件复用	通过$ref复用参数、响应、schemas	components-reuse
引用对象	$ref、摘要/描述覆盖、解析规则	core-reference-object
头部对象	响应/多部分头部、simple style、Set-Cookie、Link	core-header-object
示例对象	dataValue、serializedValue、value、externalValue、示例使用	core-example-object
标签与外部文档	Tag对象、外部文档对象、parent、kind	core-tags-and-external-docs
链接对象	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
安全要求对象	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

Best Practices

最佳实践

Topic	Description	Reference
Spec Authoring	operationId, tags, $self, components reuse, responses, security	best-practices-spec-authoring

主题	描述	参考
规范编写	operationId、tags、$self、组件复用、响应、安全机制	best-practices-spec-authoring

Advanced

进阶内容

Topic	Description	Reference
Base URI & Resolution	$self, retrieval URI, reference resolution, parsing guidance	advanced-base-uri-and-resolution
Security Filtering	Empty Paths/Path Item, Security Considerations	advanced-security-filtering

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

Key Points

关键点

OAS 3.2 root uses
```
openapi: 3.2.0
```
; at least one of
```
components
```
,
```
paths
```
, or
```
webhooks
```
MUST be present.
```
$self
```
provides the document's base URI for reference resolution; use it in multi-document OADs.
Schema Object is a superset of JSON Schema Draft 2020-12; empty schema =
```
true
```
, none =
```
false
```
.
Parameter: use either
```
schema
```
+
```
style
```
or
```
content
```
(one Media Type);
```
in: "querystring"
```
requires
```
content
```
.
Security at root is OR (one of the Security Requirement Objects); per-operation overrides;
```
{}
```
= optional.

OAS 3.2根节点使用
```
openapi: 3.2.0
```
；必须至少包含
```
components
```
、
```
paths
```
或
```
webhooks
```
中的一个。
```
$self
```
提供文档的基础URI用于引用解析；在多文档OAD中使用。
Schema对象是JSON Schema Draft 2020-12的超集；空Schema等价于
```
true
```
，无Schema等价于
```
false
```
。
参数：需使用
```
schema
```
+
```
style
```
或
```
content
```
（单个媒体类型）；
```
in: "querystring"
```
需要使用
```
content
```
。
根节点的安全机制为OR逻辑（满足任一安全要求对象即可）；可通过操作级配置覆盖；
```
{}
```
表示可选。