OpenAPI-TS 项目中的 Schema 验证问题分析与解决方案

在 OpenAPI-TS 项目中，开发者在使用 NestJS 结合 Zod 插件生成 OpenAPI 规范时可能会遇到一个特定的错误："t.required?.includes is not a function"。这个问题源于生成的 OpenAPI 规范中存在不兼容的结构，导致客户端代码生成失败。

问题背景

当开发者尝试使用 NestJS 框架配合 Zod 插件生成 OpenAPI 规范时，生成的规范在某些情况下会包含不符合预期的结构。具体表现为在 schema 定义中，required 字段被错误地设置为布尔值而非预期的数组类型。

问题分析

深入分析问题根源，可以发现在生成的 OpenAPI 规范中，某些属性的 required 字段被错误地定义为布尔值。例如：

"properties": {
  "nr": {
    "type": "string",
    "required": true
  }
}

按照 OpenAPI 3.0 规范，required 应该是对象级别的字段，用于指定哪些属性是必需的，其值应该是一个属性名数组。正确的格式应该是：

"required": ["nr"],
"properties": {
  "nr": {
    "type": "string"
  }
}

解决方案

针对这个问题，开发者可以采用以下几种解决方案：

1. 更换 Zod 插件：使用 nestjs-zod 替代原有的 zod-plugins，后者生成的 OpenAPI 规范更加符合标准。

2. 手动修正规范：在生成客户端代码前，对 OpenAPI 规范进行预处理，修正不符合规范的 required 字段。

3. 等待官方修复：OpenAPI-TS 项目团队已经注意到这个问题，未来版本可能会加入 schema 验证功能，自动检测并修正此类问题。

最佳实践建议

对于使用 NestJS 和 OpenAPI-TS 的开发者，建议：

• 在项目初期就建立 schema 验证机制
• 定期检查生成的 OpenAPI 规范是否符合标准
• 考虑使用更成熟的工具链组合，如 nestjs-zod + OpenAPI-TS
• 关注 OpenAPI-TS 项目的更新，特别是即将推出的 Zod 插件支持

总结

OpenAPI 规范的准确性对于客户端代码生成至关重要。开发者在使用工具链生成规范时，应当注意验证生成结果的合规性。通过选择合适的工具组合和建立验证机制，可以有效避免类似问题的发生，提高开发效率。