Spring Boot项目Swagger请求体错误映射非预期DTO类的问题求助

问题根源在于Swagger默认使用类的简单名称（比如Create）作为Schema标识，当两个不同嵌套结构下的类同名时，后加载的Schema会覆盖前一个，导致API文档里的请求体错误指向非预期DTO。以下是不用修改类名的解决方案：

方法1：给DTO类添加唯一Schema名称注解 #

这是最直接的方式，通过注解明确指定每个Create类的Schema名称，避免冲突。

针对Springdoc（Spring Boot 2.4+推荐，对应OpenAPI 3.x） #

在Create类上添加@Schema注解：

import io.swagger.v3.oas.annotations.media.Schema;

public interface ADTO {
    public interface Request {
        @Schema(name = "ADTO_Create")
        public class Create {
            private Long id;
            private String name;
            private String telephone;
            private String mobile;
        }
    }
}

import io.swagger.v3.oas.annotations.media.Schema;

public interface BDTO {
    public interface Request {
        @Schema(name = "BDTO_Create")
        public class Create {
            private Long id;
            private Long companyId;
            private Long userId;
            private Long contractLength;
        }
    }
}

针对Springfox（旧版本，对应Swagger 2.x） #

用@ApiModel注解替代：

import io.swagger.annotations.ApiModel;

public interface ADTO {
    public interface Request {
        @ApiModel(value = "ADTO_Create")
        public class Create {
            // 字段定义
        }
    }
}

方法2：全局配置Schema命名策略（批量处理） #

如果有大量同名DTO，不想逐个加注解，可以配置Swagger使用全限定类名作为Schema名称，自动保证唯一性。

Springdoc配置示例 #

创建Swagger配置类，自定义Schema名称生成器：

import org.springdoc.core.customizers.SchemaNameGenerator;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {
    @Bean
    public SchemaNameGenerator schemaNameGenerator() {
        // 返回类的全限定名（比如com.yourpackage.ADTO.Request.Create）
        return type -> type.getTypeName();
    }
}

Springfox配置示例 #

在Docket配置中设置命名策略：

import springfox.documentation.schema.DefaultTypeNameProvider;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.yourpackage"))
                .paths(PathSelectors.any())
                .build()
                .typeNameProvider(new DefaultTypeNameProvider() {
                    @Override
                    public String nameFor(Class<?> type) {
                        // 返回全限定类名
                        return type.getCanonicalName();
                    }
                });
    }
}

验证修改 #

重启应用后，打开Swagger UI（默认路径/swagger-ui.html或/swagger-ui），检查对应API的请求体Schema，应该已正确指向ADTO.Request.Create，字段也会和该类定义匹配。

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