编写或校验 OpenAPI 3.2 描述文档时如何组织路径…

在编写、生成或校验 OpenAPI 3.2（OAD）YAML/JSON 文档时，提供从根对象、路径操作、参数、请求响应、Schema 到安全与扩展的完整参考做法。

适用场景

解决思路

1. 根对象使用 `openapi: 3.2.0`，且 `components`、`paths`、`webhooks` 三者中至少出现一个。
2. 在多文档 OAD 中用 `$self` 声明文档基础 URI，用于解析 `$ref`、`$self` 和相对 URI。
3. 按 JSON/YAML 格式编写，注意大小写敏感、富文本处理、OAD 结构与解析规则、基础 URI 约定。
4. 区分固定字段与模式化字段：`paths` 的键、`components` 的键，以及以 `x-` 开头的规范扩展。
5. 用 Info、Contact、License 对象描述元数据。
6. 用 Server 对象与 Server Variable 描述服务器及 URL 模板变量。
7. 用 Paths Object、Path Item、Operation Object 描述路径与操作，必要时使用 `additionalOperations` 与 `query`。
8. 用路径模板（path templating）声明路径参数，遵循匹配规则与 ABNF。
9. 用 Parameter Object 描述参数，`in` 可取 path/query/header/cookie/querystring，并设置 `style`；参数在 `schema`+`style` 与 `content`（单个 Media Type）之间二选一，`in: "querystring"` 必须使用 `content`。
10. 用 Request Body 与 Media Type Object 描述请求体，支持顺序媒体类型与 `itemSchema`。
11. 用 Encoding Object 按名称或位置描述编码，设置 `contentType`、`style`、`explode`，处理 form 与 multipart。
12. 用内容键与媒体类型范围描述 Media Types，并参考 OpenAPI Media Type Registry。
13. 用 Responses Object 与 Response Object 描述响应，包括 headers、content、links。
14. 用响应键描述 HTTP 状态码，支持 `default` 与 1XX–5XX 范围（带 X）。
15. 用 Schema Object（JSON Schema Draft 2020-12 方言）、Components 与 `$ref` 解析描述 Schema 与组件；空 schema 等于 `true`，无 schema 等于 `false`。
16. 使用 JSON Schema 2020-12 关键字及 OAS 在 Schema 中的扩展。
17. 用 `allOf`、`oneOf`、`anyOf`、`discriminator` 描述组合与多态。
18. 使用 JSON Schema 类型、`format` 关键字与 OAS 方言描述数据类型与格式。
19. 用 Discriminator Object 与 XML Object（`nodeType`、`name`、`namespace`）描述判别器与 XML。
20. 通过 `$ref` 复用 parameters、responses、schemas 等组件。
21. 用 Reference Object 的 `$ref` 及 `summary`/`description` 覆盖，遵循解析规则。
22. 用 Header Object 描述响应/多部分头，`style` 为 simple，处理 `Set-Cookie`、`Link`。
23. 用 Example Object 的 `dataValue`、`serializedValue`、`value`、`externalValue` 描述示例。
24. 用 Tag Object 与 External Documentation Object 描述标签与外部文档，设置 `parent`、`kind`。
25. 用 Link Object 的 `operationRef`、`operationId`、`parameters`、`requestBody` 描述链接。
26. 使用运行时表达式 `$request`、`$response`、`$url`、`$method`（遵循 ABNF），用于 Link/Callback。
27. 用 Security Scheme、OAuth Flows、Security Requirement Object 描述安全。
28. 安全方案类型支持 `apiKey`、`http`（basic/bearer）、`mutualTLS`、`oauth2`、`openIdConnect`。
29. Security Requirement Object 遵循 OR/AND 语义：`{}` 表示可选，`[]` 表示清除，并声明 scopes。
30. 用 OAuth Flows Object 与 OAuth Flow Object 描述 `authorizationCode`、`deviceAuthorization` 等流程。
31. 用 Callback Object 与 `webhooks` 描述回调与 Webhook。
32. 用规范扩展（`x-`）及扩展注册表添加自定义扩展。
33. 遵循规范编写最佳实践：`operationId`、`tags`、`$self`、组件复用、响应、安全。
34. 处理基础 URI 与解析：`$self`、检索 URI、引用解析与解析指引。
35. 处理安全过滤：空 Paths/Path Item 与安全注意事项。
36. 根级 `security` 为 OR（任一 Security Requirement Object 满足即可），可按操作覆盖，`{}` 表示可选。