Spring Data Rest暴露接口的OpenAPI自定义配置咨询

问题原因 #

Spring Data Rest 动态生成接口，默认不会自动识别 Repository 方法上的 OpenApi（Swagger）注解，且你代码中存在注解冲突（@RequestParam 和 @PathVariable 同时使用），导致注解元数据无法被Swagger解析。

解决步骤 #

1. 添加Spring Data Rest专用的OpenApi依赖 #

确保引入SpringDoc针对Spring Data Rest的集成依赖，这是让Repository注解生效的核心：

<!-- Maven依赖 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-data-rest</artifactId>
    <version>2.2.0</version> <!-- 请匹配你的Spring Boot版本 -->
</dependency>

2. 修正Repository方法的注解 #

移除冲突的@RequestParam，保留@PathVariable，并调整参数注解的描述信息：

@Operation(summary = "根据ID获取Person信息")
@RestResource(exported = true)
@ApiResponses(value = { 
    @ApiResponse(responseCode = "404", description = "未找到对应Person"), 
    @ApiResponse(responseCode = "500", description = "服务器内部错误") 
})
@ResponseStatus(value = HttpStatus.OK)
Optional<Person> findById(@Parameter(description = "Person的唯一标识ID", name = "id") @PathVariable Integer id);

3. 配置Spring Data Rest与Swagger的集成 #

创建配置类，开启实体ID暴露并自定义Swagger文档元数据：

@Configuration
public class DataRestApiConfig implements RepositoryRestConfigurer {

    // 暴露实体ID字段，方便Swagger文档显示
    @Override
    public void configureRepositoryRestConfiguration(RepositoryRestConfiguration config) {
        config.exposeIdsFor(Person.class);
    }

    // 自定义Swagger全局配置
    @Bean
    public OpenApiCustomizer dataRestOpenApiCustomizer() {
        return openApi -> {
            openApi.info(new Info()
                    .title("Spring Data Rest 接口文档")
                    .version("1.0")
                    .description("基于Spring Data Rest自动暴露的REST接口"));
        };
    }
}

4. 开启配置文件支持 #

在application.yml中添加SpringDoc的配置，启用Spring Data Rest的Swagger支持：

springdoc:
  data-rest:
    enabled: true
  swagger-ui:
    enabled: true

完成以上步骤后，重启应用，Swagger UI就能正确显示你自定义的接口摘要、参数描述和响应信息了。

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