如何在OpenAPI规范中引用其他微服务的自定义DTO类？

方案1：在OpenAPI规范中通过扩展属性直接关联已有DTO #

OpenAPI Generator原生支持x-class-name扩展属性，你可以直接在schema定义中指定现有DTO的全限定类名，生成器识别到该属性后就不会重复生成对应类，而是直接引用你已有的类。
示例配置：

components:
  schemas:
    # 你要引用的外部DTO类名
    UserDTO:
      # 直接填已有DTO的全限定类名
      x-class-name: com.other.service.dto.UserDTO
      # 下方可保留字段定义用于规范校验、接口文档生成，不会触发重复生成
      type: object
      properties:
        id:
          type: integer
        username:
          type: string

在路径配置中正常引用该schema即可，最终生成的接口会直接使用你指定的类。

方案2：配置OpenAPI Generator的类型映射 #

如果不想修改OpenAPI规范文件，也可以在生成器的全局配置中添加类型映射，指定规范内的schema名称对应本地已存在的类。
以Maven插件配置为例：

<configuration>
  <typeMappings>
    <!-- 配置格式：规范内的schema名=对应的已有类全限定名 -->
    <typeMapping>UserDTO=com.other.service.dto.UserDTO</typeMapping>
    <typeMapping>OrderDTO=com.other.service.dto.OrderDTO</typeMapping>
  </typeMappings>
</configuration>

Gradle、CLI等其他形式的生成器都有对应的typeMappings配置项，配置逻辑一致。

方案3：公共DTO抽成独立依赖包（多团队协作推荐） #

如果多个微服务都需要复用这些DTO，可以把公共DTO单独打包成Jar包，所有需要的服务都依赖该Jar包；同时把这些DTO的OpenAPI schema定义抽成独立的公共规范文件，各个服务的OpenAPI规范通过$ref引用公共规范中的schema，再配合前两种方案指定类名，既可以保证规范统一，也不会出现重复类冲突。

• 你指定的已有DTO类必须在当前项目的类路径下，否则编译阶段会报错
• 建议保留schema的字段定义在OpenAPI规范中，既可以做接口规范校验，也能正常生成接口文档的字段说明，不会影响类的生成逻辑

内容的提问来源于stack exchange，提问作者Никита Спиридонов