用途
本技能是 OpenAPI 规范最佳实践与约定的参考资料，关注点在于 OpenAPI 规范本身未规定的「品味、约定与灰色地带」。适用于以下场景：编写新的 OpenAPI 规范；改进操作（operation）命名与组织；表达复杂数据类型（枚举、多态、可空）；处理文件上传、流式响应或 Server-Sent Events（SSE）；让规范对代码生成更友好；理解复用模式（components 与内联的取舍）。
核心原则
命名约定
Operation ID 使用小写加下划线，遵循 resource_action 模式，例如 users_list、users_get、users_create；应避免自动生成的语义缺失名称，如 GetApiV1Users。
组件名称（schema、parameter 等可复用组件）使用 PascalCase，例如 UserProfile、OrderHistory、PageLimit。
标签（tags）使用小写加连字符，便于机器处理，例如 user-management、order-processing，并附描述。更多细节参见 reference/operations.md 与 reference/components.md。
文档标准
所有 description 字段支持 CommonMark 语法进行富文本格式化，可用于说明授权要求、速率限制等信息。描述应具体可执行，例如「Returns a paginated list of active users, ordered by creation date (newest first)」，而不是笼统的「Gets users」。
示例优先使用复数 examples 字段（含命名的多个示例），相比单数 example 更利于 SDK 生成。更多细节参见 reference/examples.md。
可复用性
应为以下内容创建组件：在多个操作中使用的 schema、通用参数（分页、过滤）、通用响应（错误、成功模式）、安全方案。
应保持内联的情况：操作专属的请求体、唯一的响应结构、一次性参数。使用 $ref 引用组件，例如 $ref: '#/components/schemas/User'。更多细节参见 reference/components.md。
复杂模式速查
枚举
使用语义清晰的字符串枚举值，如 pending、approved、rejected、cancelled；避免数字字符串（"0"、"1"）、泛化值（"value1"）和不清晰的缩写（"pnd"、"appr"）。参见 reference/schemas.md#enums。
多态（oneOf / allOf / anyOf）
oneOf：值精确匹配一个 schema，用于类型区分，可配合 discriminator 使用。allOf：值匹配所有 schema，用于组合／继承，例如AdminUser由User加permissions组合而成。anyOf：值匹配一个或多个 schema，用于灵活联合，例如SearchFilter可为文本、日期或数值过滤。
参见 reference/schemas.md#polymorphism。
Discriminator
与 oneOf 配合用于高效类型识别，通过 propertyName 与 mapping 指定判别字段与映射关系，例如 petType 映射 dog／cat。各子 schema 中需将判别字段设为枚举并列入 required。参见 reference/schemas.md#discriminators。
可空类型
OpenAPI 3.1（兼容 JSON Schema 2020-12）可用 type: [string, "null"]，同时 nullable: true 仍为兼容保留。OpenAPI 3.0 使用 type: string 加 nullable: true。可选字段通过 required 数组表达。参见 reference/schemas.md#nullable。
文件上传
文件上传使用 multipart/form-data，文件字段类型为 string、格式为 binary，可将文件与 metadata 一同提交。若在 JSON 中传输 base64 编码文件，则使用 format: byte。参见 reference/request-bodies.md#file-uploads。
Server-Sent Events（SSE）
流式响应用 text/event-stream 表达，schema 为字符串并说明事件格式，可配合示例展示事件数据。参见 reference/responses.md#streaming。
字段参考索引
- Operations：operationId、方法、标签、弃用 → reference/operations.md
- Schemas：数据类型、多态、枚举、可空 → reference/schemas.md
- Parameters：路径、查询、头部、Cookie 参数 → reference/parameters.md
- Request Bodies：内容类型、文件上传、编码 → reference/request-bodies.md
- Responses：状态码、流式、错误模式 → reference/responses.md
- Components：可复用定义与组织 → reference/components.md
- Security：认证方案、作用域、细粒度控制 → reference/security.md
- Examples：单个与多个示例、放置位置 → reference/examples.md
SDK 生成注意事项
面向 SDK 生成编写规范时：始终定义 operationId（否则方法名自动生成）；提供丰富示例（有助于生成更好的文档与测试）；明确必填字段（影响 SDK 方法签名）；对 oneOf 使用 discriminator（生成类型安全的联合类型）；记录错误响应（生成更好的错误处理代码）。资料中给出的示例操作会生成类似 sdk.users.list({limit: 20, offset: 0}) 的调用形式，但 SDK 的实际生成结果与具体工具相关，暂未提供进一步说明。
常见陷阱
资料列出了应避免与应遵循的做法。应避免：使用「Gets data」「Returns object」这类笼统描述；混用命名约定；忘记 operationId；在本应使用复数 examples 时使用单数 example；把所有字段都设为必填；把所有内容都内联；把所有内容都用引用；忘记记录错误响应；使用无解释的魔法数字；省略内容类型。应遵循：提供可执行、具体的描述；全程使用一致的命名模式；为每个操作定义清晰的 operationId；使用带命名的 examples；仔细权衡必填与可选字段；在复用性与清晰度之间平衡；记录所有预期响应（成功与错误）；说明约束与校验规则；明确内容类型与格式。
限制
本资料为编写 OpenAPI 规范的参考指南，未涉及具体工具安装、运行时依赖、收费或价格信息，相关内容暂未提供。