Swagger文档是否仅需包含@Controller层？Spring Boot异常情况咨询

是否正常？ #

这种情况不正常。默认配置下，SpringDoc-OpenAPI应该只识别并生成@Controller/@RestController层的接口文档，Service和Entity层本不该出现在最终的API文档里。

核心原因分析 #

• 扫描范围未限制：如果没明确指定扫描的包路径，SpringDoc可能会默认扫描整个项目的@Component派生类（@Service属于@Component的子类），导致Service类被误判为API端点。
• Service类误用API注解：要是你的@Service类上不小心加了@RestController、@RequestMapping、@Operation这类OpenAPI相关注解，SpringDoc会把它当作API接口处理，进而生成对应的文档。
• Entity直接作为接口参数/返回值：如果Controller方法直接返回Entity类、或者用Entity作为请求参数，SpringDoc会自动把Entity的字段纳入API模型文档中，看起来像是把Entity层包含进了文档里。

解决方法 #

• 限定扫描包范围：在配置类里通过GroupedOpenApi指定只扫描Controller所在的包：

  @Configuration
  public class OpenApiConfig {
      @Bean
      public OpenAPI customOpenAPI() {
          return new OpenAPI()
                  .info(new Info().title("项目API文档").version("v1.0"));
      }
  
      @Bean
      public GroupedOpenApi publicApi() {
          return GroupedOpenApi.builder()
                  .group("public-api")
                  .packagesToScan("com.yourproject.controller") // 仅扫描Controller包
                  .build();
      }
  }
  

• 清理Service类的API注解：检查所有@Service类，移除误加的@RestController、@RequestMapping等API相关注解，确保只有Controller层使用这类注解。
• 用DTO封装请求/响应：不要直接用Entity类作为接口的参数或返回值，创建专门的DTO类（比如UserDTO），在Controller层用DTO做数据传输，这样SpringDoc只会生成DTO的模型文档，Entity层就不会出现在API文档中了。

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