如何在Swagger Codegen文件中引用Spring Boot已有自定义DTO类？

一、指定已有类作为接口参数的方法 #

1. 使用x-java-type扩展字段（直接关联类） #

针对你提供的Swagger 2.0格式，可以直接在请求体的schema中添加x-java-type字段，指定已有DTO类的全限定类名，Swagger工具（如SpringDoc、Swagger Codegen的Java插件）会自动引用该类，而非重新生成：

paths:
    /someDto/createSomeDto:
        post:
            summary: Creates a new someDto
            operationId: createSomeDto
            parameters:
                - name: someDto
                  in: body
                  description: data transfer object
                  schema:
                      x-java-type: com.yourproject.dto.SomeDto  # 替换为你的DTO类全路径
            responses:
                '200':
                    description: 请求成功

如果是使用OpenAPI 3.0+规范（推荐），则用requestBody替代body参数，写法如下：

paths:
    /someDto/createSomeDto:
        post:
            summary: Creates a new someDto
            operationId: createSomeDto
            requestBody:
                description: data transfer object
                content:
                    application/json:
                        schema:
                            x-java-type: com.yourproject.dto.SomeDto
            responses:
                '200':
                    description: 请求成功

2. 定义组件引用（更规范的复用方式） #

先在YAML的components/schemas中定义DTO的引用并关联已有类，之后在接口中通过$ref复用该定义：

components:
    schemas:
        SomeDto:
            x-java-type: com.yourproject.dto.SomeDto  # 关联已有类

paths:
    /someDto/createSomeDto:
        post:
            summary: Creates a new someDto
            operationId: createSomeDto
            parameters:
                - name: someDto
                  in: body
                  description: data transfer object
                  schema:
                      $ref: '#/components/schemas/SomeDto'  # 引用定义好的组件
            responses:
                '200':
                    description: 请求成功

如果你的DTO类上已经添加了Swagger注解（如SpringDoc的@Schema或Swagger 2的@ApiModel），Swagger工具会自动识别该类的元数据，此时甚至可以省略x-java-type，直接通过类的注解名称引用即可。

二、为何没有专门的“导入”关键字？ #

Swagger/OpenAPI是语言无关的API描述规范，设计目标是兼容所有编程语言，而“导入”是Java、Python等特定语言的语法概念，不属于通用API描述的范畴。

为了兼顾通用性和语言特定需求，规范采用**扩展字段（如x-java-type）**的方式来实现针对特定语言的自定义配置——这类以x-开头的字段是规范预留的自定义扩展位，不同语言的Swagger工具会识别并处理对应的扩展逻辑，既保持了规范的中立性，又能满足各语言的特殊需求。

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