OpenAPI (Swagger) 代码生成注意事项

利用 OpenAPI 文档自动生成接口代码可以极大地提高开发效率。为了确保生成的代码具有良好的可读性和稳定性，在编写文档时应遵循以下注意事项。

核心规范要求

维度	关键要求	说明
命名	固定的 operationId	operationId 是生成函数/方法的名称依据。必须保持全局唯一且固定，否则接口重命名会导致调用方代码报错。
模型	显式定义 Schema	尽量在 components/schemas 中定义可复用的模型，避免使用匿名对象，以确保生成一致的数据类或接口。
校验	明确必填项 (required)	务必标注必填字段。这将直接影响生成代码中的可选类型（如 TypeScript 的 ? 或 Java 的 Optional）。
注释	完善 summary/description	文档中的描述信息会被提取为代码注释，良好的描述有助于调用方理解接口用途。

进阶注意事项

• 标签管理 (tags): 大多数生成工具会根据 tags 对代码进行拆分和分组（如按模块生成文件），建议保持标签简洁且具有逻辑性。
• 枚举值 (enum): 为字段定义明确的 enum 列表，这样生成的代码会包含类型安全的枚举类型，而非通用的字符串。
• 路径参数: 确保路径参数（Path Parameters）命名清晰，这会直接影响生成方法的入参名称。

---