OpenAPI生成器两大问题：资源顺序不一致及跨模块枚举缺失

问题1：API资源与Schema顺序不一致导致差异对比失效 #

日常开发中，我们通常通过以下流程追踪服务修改带来的API变化：

• 生成服务初始OpenAPI定义
• 修改服务代码
• 重新生成OpenAPI定义
• 对比两个版本，识别新增/移除内容

但每次生成的OpenAPI中，API资源和Schema条目的顺序不固定，直接对比会产生大量无意义的顺序变更差异，无法快速定位真正的内容改动。

解决方法 #

• 启用生成工具的排序配置：如果使用的OpenAPI生成工具支持，开启按字母排序的配置项。例如设置sortPropertiesAlphabetically: true和sortParametersAlphabetically: true，强制生成的JSON/YAML文件按固定顺序排列资源和Schema。
• 预处理文件后对比：在对比前用工具对OpenAPI文件做排序格式化。以JSON为例，使用jq工具：

  jq -S . old-openapi.json > sorted-old.json
  jq -S . new-openapi.json > sorted-new.json
  

  对比排序后的文件即可过滤掉顺序差异，聚焦内容变更。
• 使用忽略顺序的对比工具：选择支持忽略JSON/YAML键顺序的对比工具，比如IntelliJ IDEA等IDE的内置对比功能，或使用diff命令结合排序参数，避免顺序干扰。

问题2：跨模块枚举未被纳入OpenAPI生成结果 #

当枚举类型定义在service.bal所在模块之外的其他模块时，生成的OpenAPI文档中不会包含该枚举的Schema定义，导致API文档缺失关键的枚举说明。

解决方法 #

• 显式引用跨模块枚举：在service.bal所在模块中，导入该枚举并将其作为API接口的参数、返回值或结构体字段类型使用，确保生成工具能识别到该枚举的依赖并将其加入OpenAPI。
• 扩展生成工具的扫描范围：检查OpenAPI生成工具的配置，添加包含目标枚举的模块路径到扫描范围中，让工具自动发现并生成该枚举的Schema。
• 手动补充枚举定义：如果上述方法无法生效，可在生成后的OpenAPI文档中手动添加该枚举的Schema，或在代码中通过自定义OpenAPI扩展的方式显式声明枚举结构。

内容的提问来源于stack exchange，提问作者Hasitha