Spring Boot 3迁移后访问/v3/api-docs报MappingException求助

将Spring Boot 2.7.3迁移至3版本，已完成对应变更，替换springdoc-openapi-ui为springdoc-openapi-starter-webmvc-ui:2.0.0。应用启动正常，但访问/v3/api-docs时抛出MappingException，其他API运行正常，未做重大代码或配置变更，无法定位根因。

错误栈信息 #

org.springframework.data.mapping.MappingException: Cannot get or create PersistentEntity for type com.example.envoy.peoplepickerhandler.domain.entity.file.PersonCustom; PersistentEntities knows about 0 MappingContext instances and therefore cannot identify a single responsible one; Please configure the initialEntitySet through an entity scan using the base package in your configuration to pre initialize contexts
 at org.springframework.data.mapping.context.PersistentEntities.lambda$getRequiredPersistentEntity$0(PersistentEntities.java:120)
 at java.base/java.util.Optional.orElseThrow(Optional.java:403)
 at org.springframework.data.mapping.context.PersistentEntities.getRequiredPersistentEntity(PersistentEntities.java:119)
 at org.springdoc.core.providers.SpringRepositoryRestResourceProvider.getRouterOperations(SpringRepositoryRestResourceProvider.java:221)
 at org.springdoc.webmvc.api.OpenApiResource.lambda$getPaths$1(OpenApiResource.java:170)
 at java.base/java.util.Optional.ifPresent(Optional.java:178)
 at org.springdoc.webmvc.api.OpenApiResource.lambda$getPaths$2(OpenApiResource.java:169)
 at java.base/java.util.Optional.ifPresent(Optional.java:178)
 at org.springdoc.webmvc.api.OpenApiResource.getPaths(OpenApiResource.java:165)
 at org.springdoc.api.AbstractOpenApiResource.getOpenApi(AbstractOpenApiResource.java:366)
 at org.springdoc.webmvc.api.OpenApiResource.openapiJson(OpenApiResource.java:140)
 at org.springdoc.webmvc.api.OpenApiWebMvcResource.openapiJson(OpenApiWebMvcResource.java:117)
 at org.springdoc.webmvc.api.MultipleOpenApiWebMvcResource.openapiJson(MultipleOpenApiWebMvcResource.java:89)
 at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
 at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:77)
 at java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
 at java.base/java.lang.reflect.Method.invoke(Method.java:568)
 at org.springframework.web.method.support.InvocableHandlerMethod.doInvoke(InvocableHandlerMethod.java:207)
 at org.springframework.web.method.support.InvocableHandlerMethod.invokeForRequest(InvocableHandlerMethod.java:152)
 at org.springframework.web.servlet.mvc.method.annotation.ServletInvocableHandlerMethod.invokeAndHandle(ServletInvocableHandlerMethod.java:117)
 at org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter.invokeHandlerMethod(RequestMappingHandlerAdapter.java:884)
 at org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter.handleInternal(RequestMappingHandlerAdapter.java:797)
 at org.springframework.web.servlet.mvc.method.AbstractHandlerMethodAdapter.handle(AbstractHandlerMethodAdapter.java:87)
 at org.springframework.web.servlet.DispatcherServlet.doDispatch(DispatcherServlet.java:1080)
 at org.springframework.web.servlet.DispatcherServlet.doService(DispatcherServlet.java:973)
 at org.springframework.web.servlet.FrameworkServlet.processRequest(FrameworkServlet.java:1010)
 at org.springframework.web.servlet.FrameworkServlet.doGet(FrameworkServlet.java:902)
 at jakarta.servlet.http.HttpServlet.service(HttpServlet.java:705)
 at org.springframework.web.servlet.FrameworkServlet.service(FrameworkServlet.java:884)
 at jakarta.servlet.http.HttpServlet.service(HttpServlet.java:814)
 at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:223)
 at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:158)
 at org.apache.tomcat.websocket.server.WsFilter.doFilter(WsFilter.java:53)
 at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:185)
 at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:158)
 at org.springframework.security.web.FilterChainProxy.lambda$doFilterInternal$3(FilterChainProxy.java:231)
 at org.springframework.security.web.ObservationFilterChainDecorator$FilterObservation$SimpleFilterObservation.lambda$wrap$1(ObservationFilterChainDecorator.java:399)
 at org.springframework.security.web.ObservationFilterChainDecorator$AroundFilterObservation$SimpleAroundFilterObservation.lambda$wrap$1(ObservationFilterChainDecorator.java:297)
 at org.springframework.security.web.ObservationFilterChainDecorator.lambda$wrapSecured$0(ObservationFilterChainDecorator.java:79)
 at org.springframework.security.web.ObservationFilterChainDecorator$VirtualFilterChain.doFilter(ObservationFilterChainDecorator.java:125)
 at org.springframework.security.web.access.intercept.AuthorizationFilter.doFilter(AuthorizationFilter.java:100)
 at org.springframework.security.web.ObservationFilterChainDecorator$ObservationFilter.wrapFilter(ObservationFilterChainDecorator.java:186)
 at org.springframework.security.web.ObservationFilterChainDecorator$ObservationFilter.doFilter(ObservationFilterChainDecorator.java:173)
 at org.springframework.security.web.ObservationFilterChainDecorator$VirtualFilterChain.doFilter(ObservationFilterChainDecorator.java:134)
 at org.springframework.security.web.access.ExceptionTranslationFilter.doFilter(ExceptionTranslationFilter.java:126)
 at org.springframework.security.web.access.ExceptionTranslationFilter.doFilter(ExceptionTranslationFilter.java:120)
 at org.springframework.security.web.ObservationFilterChainDecorator$ObservationFilter.wrapFilter(ObservationFilterChainDecorator.java:186)
 at org.springframework.security.web.ObservationFilterChainDecorator$ObservationFilter.doFilter(ObservationFilterChainDecorator.java:173)
 at org.springframework.security.web.ObservationFilterChainDecorator$VirtualFilterChain.doFilter(ObservationFilterChainDecorator.java:134)
 at org.springframework.security.web.session.SessionManagementFilter.doFilter(SessionManagementFilter.java:131)
 at org.springframework.security.web.session.SessionManagementFilter.doFilter(SessionManagementFilter.java:85)
 at org.springframework.security.web.ObservationFilterChainDecorator$ObservationFilter.wrapFilter(ObservationFilterChainDecorator.java:186)
 at org.springframework.security.web.ObservationFilterChainDecorator$ObservationFilter.doFilter(ObservationFilterChainDecorator.java:173)
 at org.springframework.security.web.ObservationFilterChainDecorator$VirtualFilterChain.doFilter(ObservationFilterChainDecorator.java:134)
 at org.springframework.security.web.authentication.AnonymousAuthenticationFilter.doFilter(AnonymousAuthenticationFilter.java:100)
 at org.springframework.security.web.ObservationFilterChainDecorator$ObservationFilter.wrapFilter(ObservationFilterChainDecorator.java:186)
 at org.springframework.security.web.ObservationFilterChainDecorator$ObservationFilter.doFilter(ObservationFilterChainDecorator.java:173)
 at org.springframework.security.web.ObservationFilterChainDecorator$VirtualFilterChain.doFilter(ObservationFilterChainDecorator.java:134)
 at org.springframework.security.web.servletapi.SecurityContextHolderAwareRequestFilter.doFilter(SecurityContextHolderAwareRequestFilter.java:179)
 at org.springframework.security.web.ObservationFilterChainDecorator$ObservationFilter.wrapFilter(ObservationFilterChainDecorator.java:186)
 at org.springframework.security.web.ObservationFilterChainDecorator$ObservationFilter.doFilter(ObservationFilterChainDecorator.java:173)
 at org.springframework.security.web.ObservationFilterChainDecorator$VirtualFilterChain.doFilter(ObservationFilterChainDecorator.java:134)
 at org.springframework.security.web.savedrequest.RequestCacheAwareFilter.doFilter(RequestCacheAwareFilter.java:63)
 at org.springframework.security.web.ObservationFilterChainDecorator$ObservationFilter.wrapFilter(ObservationFilterChainDecorator.java:186)
 at org.springframework.security.web.ObservationFilterChainDecorator$ObservationFilter.doFilter(ObservationFilterChainDecorator.java:173)
 at org.springframework.security.web.ObservationFilterChainDecorator$VirtualFilterChain.doFilter(ObservationFilterChainDecorator.java:134)
 at com.pwc.envoy.peoplepickerhandler.security.jwt.JWTFilter.doFilter(JWTFilter.java:57)
 at org.springframework.security.web.ObservationFilterChainDecorator$ObservationFilter.wrapFilter(ObservationFilterChainDecorator.java:186)
 at org.springframework.security.web.ObservationFilterChainDecorator$ObservationFilter.doFilter(ObservationFilterChainDecorator.java:173)
 at org.springframework.security.web.ObservationFilterChainDecorator$VirtualFilterChain.doFilter(ObservationFilterChainDecorator.java:134)
 at org.springframework.security.web.authentication.logout.LogoutFilter.doFilter(LogoutFilter.java:107)
 at org.springframework.security.web.authentication.logout.LogoutFilter.doFilter(LogoutFilter.java:93)
 at org.springframework.security.web.ObservationFilterChainDecorator$ObservationFilter.wrapFilter(ObservationFilterChainDecorator.java:186)
 at org.springframework.security.web.ObservationFilterChainDecorator$ObservationFilter.doFilter(ObservationFilterChainDecorator.java:173)
 at org.springframework.security.web.ObservationFilterChainDecorator$VirtualFilterChain.doFilter(ObservationFilterChainDecorator.java:134)
 at org.springframework.security.web.header.HeaderWriterFilter.doHeadersAfter(HeaderWriterFilter.java:90)
 at org.springframework.security.web.header.HeaderWriterFilter.doFilterInternal(HeaderWriterFilter.java:75)
 at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:116)
 at org.springframework.security.web.ObservationFilterChainDecorator$ObservationFilter.wrapFilter(ObservationFilterChainDecorator.java:186)
 at org.springframework.security.web.ObservationFilterChainDecorator$ObservationFilter.doFilter(ObservationFilterChainDecorator.java:173)
 at org.springframework.security.web.ObservationFilterChainDecorator$VirtualFilterChain.doFilter(ObservationFilterChainDecorator.java:134)
 at org.springframework.security.web.context.SecurityContextHolderFilter.doFilter(SecurityContextHolderFilter.java:82)
 at org.springframework.security.web.context.SecurityContextHolderFilter.doFilter(SecurityContextHolderFilter.java:69)
 at org.springframework.security.web.ObservationFilterChainDecorator$ObservationFilter.wrapFilter(ObservationFilterChainDecorator.java:186)
 at org.springframework.security.web.ObservationFilterChainDecorator$ObservationFilter.doFilter(ObservationFilterChainDecorator.java:173)
 at org.springframework.security.web.ObservationFilterChainDecorator$VirtualFilterChain.doFilter(ObservationFilterChainDecorator.java:134)
 at org.springframework.security.web.context.request.async.WebAsyncManagerIntegrationFilter.doFilterInternal(WebAsyncManagerIntegrationFilter.java:62)
 at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:116)
 at org.springframework.security.web.ObservationFilterChainDecorator$ObservationFilter.wrapFilter(ObservationFilterChainDecorator.java:186)
 at org.springframework.security.web.ObservationFilterChainDecorator$ObservationFilter.doFilter(ObservationFilterChainDecorator.java:173)
 at org.springframework.security.web.ObservationFilterChainDecorator$VirtualFilterChain.doFilter(ObservationFilterChainDecorator.java:134)
 at org.springframework.security.web.session.DisableEncodeUrlFilter.doFilterInternal(DisableEncodeUrlFilter.java:42)
 at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:116)
 at org.springframework.security.web.ObservationFilterChainDecorator$ObservationFilter.wrapFilter(ObservationFilterChainDecorator.java:186)
 at org.springframework.security.web.ObservationFilterChainDecorator$AroundFilterObservation$SimpleAroundFilterObservation.lambda$wrap$0(ObservationFilterChainDecorator.java:280)
 at org.springframework.security.web.ObservationFilterChainDecorator$ObservationFilter.doFilter(ObservationFilterChainDecorator.java:170)
 at org.springframework.security.web.ObservationFilterChainDecorator$VirtualFilterChain.doFilter(ObservationFilterChainDecorator.java:134)
 at org.springframework.security.web.FilterChainProxy.doFilterInternal(FilterChainProxy.java:233)
 at org.springframework.security.web.FilterChainProxy.doFilter(FilterChainProxy.java:191)
 at org.springframework.web.filter.DelegatingFilterProxy.invokeDelegate(DelegatingFilterProxy.java:351)
 at org.springframework.web.filter.DelegatingFilterProxy.doFilter(DelegatingFilterProxy.java:267)
 at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:185)
 at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:158)
 at org.springframework.web.filter.RequestContextFilter.doFilterInternal(RequestContextFilter.java:100)
 at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:116)
 at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:185)
 at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:158)
 at org.springframework.web.filter.FormContentFilter.doFilterInternal(FormContentFilter.java:93)
 at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:116)
 at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:185)
 at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:158)
 at org.springframework.web.filter.ServerHttpObservationFilter.doFilterInternal(ServerHttpObservationFilter.java:109)
 at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:116)
 at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:185)
 at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:158)
 at org.springframework.web.filter.CharacterEncodingFilter.doFilterInternal(CharacterEncodingFilter.java:201)
 at org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:116)
 at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:185)
 at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:158)
 at org.apache.catalina.core.StandardWrapperValve.invoke(StandardWrapperValve.java:177)
 at org.apache.catalina.core.StandardContextValve.invoke(StandardContextValve.java:97)
 at org.apache.catalina.authenticator.AuthenticatorBase.invoke(AuthenticatorBase.java:542)
 at org.apache.catalina.core.StandardHostValve.invoke(StandardHostValve.java:119)
 at org.apache.catalina.valves.ErrorReportValve.invoke(ErrorReportValve.java:92)
 at org.apache.catalina.core.StandardEngineValve.invoke(StandardEngineValve.java:78)
 at org.apache.catalina.connector.CoyoteAdapter.service(CoyoteAdapter.java:357)
 at org.apache.coyote.http11.Http11Processor.service(Http11Processor.java:400)
 at org.apache.coyote.AbstractProcessorLight.process(AbstractProcessorLight.java:65)
 at org.apache.coyote.AbstractProtocol$ConnectionHandler.process(AbstractProtocol.java:859)
 at org.apache.tomcat.util.net.NioEndpoint$SocketProcessor.doRun(NioEndpoint.java:1734)
 at org.apache.tomcat.util.net.SocketProcessorBase.run(SocketProcessorBase.java:52)
 at org.apache.tomcat.util.threads.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1191)
 at org.apache.tomcat.util.threads.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:659)
 at org.apache.tomcat.util.threads.TaskThread$WrappingRunnable.run(TaskThread.java:61)
 at java.base/java.lang.Thread.run(Thread.java:833)

当前Swagger配置类 #

@Configuration
@OpenAPIDefinition(info = @Info(title = "People Picker Handler API", version = "1.0"),
        servers = {@Server(url = "/api/peoplepickerhandlerms", description = "Default Server URL")},
        security = {@SecurityRequirement(name = "bearerAuth")})
@SecurityScheme(name = "bearerAuth", scheme = "bearer", bearerFormat = "JWT", type = SecuritySchemeType.HTTP, in = SecuritySchemeIn.HEADER)
public class SwaggerConfig {
 
   @Bean
   public GroupedOpenApi publicApi() {
     return GroupedOpenApi.builder().group("people-picker-handler-apis")
           .pathsToMatch("/").packagesToScan("com.example.envoy.peoplepickerhandler")
           .headersToMatch(org.apache.tomcat.websocket.Constants.AUTHORIZATION_HEADER_NAME).build();
   }
}

根因 #

springdoc的SpringRepositoryRestResourceProvider生成OpenAPI文档时，尝试获取PersonCustom实体的PersistentEntity，但Spring Data的PersistentEntities找不到对应的MappingContext。原因有两点：

1. Spring Boot 3迁移后，springdoc-starter默认自动检测Spring Data Repository并生成对应API文档，但项目未正确配置Spring Data实体扫描，导致PersonCustom未被识别；
2. GroupedOpenApi中pathsToMatch("/")范围过广，触发springdoc扫描所有路径，包括Spring Data相关端点，进而触发实体检测。

解决方案 #

方案1：禁用Spring Data Repository的OpenAPI文档生成 #

若不需要生成Repository相关的接口文档，在配置文件中添加：

springdoc.api-docs.enable-spring-data-rest=false

方案2：配置Spring Data实体扫描 #

若需要保留Repository的文档，确保Spring Data能扫描到实体：
在Spring Boot启动类上添加@EntityScan注解指定实体