如何在Swagger-UI中展示未关联接口的Spring Boot实体模型？

不用新增控制器，有几种简单方案可以把Address实体添加到Swagger的Models中：

方案1：给实体类添加Swagger注解 #

直接在Address类上加上@ApiModel注解，Swagger会自动识别该实体并加入Models列表：

@Entity
@Table(name = "Address")
@ApiModel(description = "地址实体类") // 添加此注解
public class Address {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    @Column(name = "emp_id")
    @ApiModelProperty(value = "主键ID") // 可选，给字段添加说明
    private Long id;

    @Column(name = "first_name")
    @ApiModelProperty(value = "名字")
    private String firstName;

    @Column(name = "last_name")
    @ApiModelProperty(value = "姓氏")
    private String lastName;

    @Column(name = "email_id")
    @ApiModelProperty(value = "邮箱地址")
    private String emailId;

    // getter、setter方法...
}

添加@ApiModel后，即便没有控制器引用这个实体，它也会出现在Swagger-UI的Models里。

方案2：配置Swagger主动指定实体类 #

如果不想给实体加注解，可以在Swagger配置类中，通过Docket的additionalModels方法指定要包含的实体：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.your.package"))
                .paths(PathSelectors.any())
                .build()
                // 主动添加Address实体
                .additionalModels(typeResolver -> typeResolver.resolve(Address.class));
    }

    @Autowired
    private TypeResolver typeResolver;
}

如果用的是Swagger 3.x（SpringDoc），配置方式类似：

@Configuration
public class SpringDocConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .components(new Components()
                        // 将Address加入schemas
                        .addSchemas("Address", SchemaUtils.getSchema(typeResolver, Address.class)));
    }

    @Autowired
    private TypeResolver typeResolver;
}

方案3：通过已有控制器的注解间接引用 #

可以在现有控制器的方法上，用@ApiResponse标注引用Address实体，Swagger会自动把它加入Models：

@RestController
@RequestMapping("/employees")
public class EmployeeController {
    @GetMapping("/{id}")
    @ApiResponse(responseCode = "200", description = "查询成功", content = @Content(schema = @Schema(implementation = Employee.class)))
    // 额外添加对Address实体的引用，实际业务逻辑无需修改
    @ApiResponse(responseCode = "200", description = "关联地址实体", content = @Content(schema = @Schema(implementation = Address.class)))
    public ResponseEntity<Employee> getEmployee(@PathVariable Long id) {
        // 原有业务逻辑...
    }
}

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