如何基于Ocelot多Swagger定义用openapi-generator-cli生成TS API与模型

1、多Swagger定义生成API服务与Model的方法 #

两种常用方案，可根据你的业务场景选择：

方案一：按微服务分目录独立生成 #

这是最简便、耦合度最低的方案，给每个微服务的Swagger JSON单独执行生成命令，指定不同的输出目录即可，还可以通过附加参数避免类名冲突：

# 生成项目服务API代码
openapi-generator-cli generate -g typescript-angular -o ./openapi/project -i http://localhost:xxxx/swagger/docs/v1/project --additional-properties=apiModulePrefix=Project
# 生成用户服务API代码
openapi-generator-cli generate -g typescript-angular -o ./openapi/user -i http://localhost:xxxx/swagger/docs/v1/user --additional-properties=apiModulePrefix=User
# 生成订单服务API代码
openapi-generator-cli generate -g typescript-angular -o ./openapi/order -i http://localhost:xxxx/swagger/docs/v1/order --additional-properties=apiModulePrefix=Order

如果需要统一导出所有API和模型，可以在根目录新增index.ts做聚合：

// openapi/index.ts
export * from './project';
export * from './user';
export * from './order';

方案二：合并Swagger定义后统一生成 #

如果你的多个微服务存在大量公共模型，想要避免生成重复的类定义，可以先通过swagger-merger等工具将多个Swagger JSON合并为单个OpenAPI规范文件，再执行一次生成命令即可。注意合并前需要先处理不同服务重名的Schema定义，避免覆盖。

2、多Swagger定义的使用规范与拆分合理性 #

按微服务拆分独立Swagger定义是微服务架构下的标准实践，完全合理，原因如下：

• 每个微服务职责独立，单独维护API定义不会和其他服务耦合，单个服务迭代更新API时只需要修改自己的Swagger，不会影响其他服务的生成代码
• 前端可以对应业务模块按需引入对应微服务的API代码，打包时可以裁剪未使用的服务代码，减小包体积

多定义的常用使用方式：

• 内部开发时优先使用分服务的独立Swagger，各业务团队只需要关注自己对接的服务定义即可
• 后端侧可以将通用分页、统一返回结构等公共Schema抽为公共依赖，所有微服务的Swagger统一引用，避免生成重复的模型类
• 如果需要对外暴露统一的API对接入口，可以在Ocelot网关层做Swagger聚合，对外仅提供一份合并后的文档，降低第三方对接成本
• 不建议无差别合并所有微服务的Swagger定义，服务数量较多时合并后会导致定义冗余，单次生成代码的效率降低，且单个服务迭代会触发整份代码更新，增加冲突风险

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