升级OpenAPI 3后生成多余实体与API端点的配置问题

1. 拦截多余端点生成（只保留带注解的Controller） #

升级后OpenAPI默认会扫描所有Spring组件（包括Repository、Service），导致生成不存在的Crud端点。通过配置限定扫描范围解决：

创建OpenAPIConfig配置类，指定只扫描你的Controller包，同时排除内部实体、Repository等不需要的包：

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenAPIConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("你的API文档标题").version("1.0"));
    }

    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .group("public-api")
                // 替换成你实际的Controller包路径
                .packagesToScan("com.yourproject.controller")
                // 排除内部实体、Repository等包，按需添加
                .packagesToExclude("com.yourproject.entity", "com.yourproject.repository")
                .build();
    }
}

2. 禁用Spring Data REST自动生成端点 #

如果项目引入了Spring Data REST，它会自动为Repository生成Crud接口，OpenAPI会把这些也纳入文档。直接在配置文件里关闭：

application.properties #

spring.data.rest.enabled=false

application.yml #

spring:
  data:
    rest:
      enabled: false

3. 隐藏内部实体Schema #

如果内部实体还是出现在文档的Schema列表里，给不需要展示的实体类加@Hidden注解（来自io.swagger.v3.oas.annotations.Hidden）：

import io.swagger.v3.oas.annotations.Hidden;

@Hidden
public class CustomerInfo {
    // 实体字段...
}

或者在配置类里限定只扫描DTO所在的包，确保只有API用到的DTO被展示：

@Bean
public GroupedOpenApi publicApi() {
    return GroupedOpenApi.builder()
            .group("public-api")
            .packagesToScan("com.yourproject.controller", "com.yourproject.dto")
            .build();
}

4. 排查OpenAPI端点访问异常 #

由于看不到截图，给你通用排查方向：

• 看控制台的异常栈，定位是类缺失、权限问题还是序列化错误。
• 确认OpenAPI依赖和Spring Boot 3（Java17适配版本）兼容，比如用springdoc-openapi-starter-webmvc-ui 2.2.0及以上版本。
• 检查端点路径是否正确：默认是/v3/api-docs（JSON接口）和/swagger-ui.html（UI页面）。
• 如果是序列化异常，检查实体类里的特殊类型（比如LocalDateTime）是否配置了正确的序列化器，Java17下可能需要额外配置Jackson的模块。

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