Spring Boot项目@OpenAPIDefinition注解不生效如何解决

问题根因 #

你遇到的配置不生效问题核心是依赖方案和参考的配置规则不匹配：

• 你当前使用的是Springfox 3.x作为OpenAPI集成方案，而你参考的是Springdoc项目的配置规则，两者是完全独立的OpenAPI Spring Boot集成实现，配置逻辑不通用。Springfox 3.x原生对@OpenAPIDefinition注解的支持不完整，因此注解不生效属于正常现象。
• 你额外引入的swagger-jaxrs2、swagger-jaxrs2-servlet-initializer-v2属于JAX-RS场景下的Swagger依赖，Spring Boot WebFlux场景完全不需要，反而会和现有Springfox依赖产生冲突，影响配置加载。

解决方案 #

方案1：继续使用Springfox框架 #

1. 清理冲突依赖，删除pom.xml中以下3个依赖（springfox-boot-starter已经自带swagger-ui，无需单独引入）：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>
  <groupId>io.swagger.core.v3</groupId>
  <artifactId>swagger-jaxrs2</artifactId>
  <version>2.1.2</version>
</dependency>
<dependency>
  <groupId>io.swagger.core.v3</groupId>
  <artifactId>swagger-jaxrs2-servlet-initializer-v2</artifactId>
  <version>2.1.2</version>
</dependency>

2. 新增Springfox原生配置类，自定义API基础信息：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
@EnableOpenApi
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                // 替换为你的Controller接口所在包路径
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("the title")
                .description("My API")
                .contact(new Contact("Fred", "http://gigantic-server.com", "Fred@gigagantic-server.com"))
                .license("Apache 2.0")
                .licenseUrl("http://foo.bar")
                .version("0.0")
                .build();
    }
}

3. 删除启动类上的@OpenAPIDefinition注解，重启项目后配置即可生效。

方案2（更推荐）：切换至Springdoc框架 #

Springfox框架自2020年起已停止维护，对高版本Spring Boot兼容性差，切换到仍在活跃维护的Springdoc框架可以直接兼容你写的@OpenAPIDefinition注解：

1. 删除所有Springfox相关依赖、以及多余的swagger-jaxrs2系列依赖。
2. 引入Springdoc WebFlux适配依赖：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-webflux-ui</artifactId>
    <version>1.6.15</version>
</dependency>

3. 原有@OpenAPIDefinition注解无需修改，直接生效。原有的@ApiIgnore注解可以替换为@Hidden注解实现相同的隐藏效果，接口文档访问路径和之前一致。

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