Spring Boot Swagger：如何根据Spring Profile忽略指定API？

当然可以实现！而且有几种不同的方案，适配不同的场景需求，我给你一一拆解：

方案一：用SpEL直接控制@ApiOperation的hidden属性（最简洁） #

Spring Fox的@ApiOperation注解提供了hidden属性，支持通过SpEL表达式动态判断是否隐藏API。你可以直接利用Spring Boot的环境变量来控制：

@RestController
public class MyController {

    // 私有API：仅在生产环境隐藏，QA/Dev环境可见
    @GetMapping("/private-api")
    @ApiOperation(
        value = "私有接口示例",
        hidden = "${spring.profiles.active == 'prod'}"
    )
    public ResponseEntity<String> privateApi() {
        return ResponseEntity.ok("私有内容");
    }

    // 公开API：所有环境可见
    @GetMapping("/public-api")
    public ResponseEntity<String> publicApi() {
        return ResponseEntity.ok("公开内容");
    }
}

只要你的Spring Boot环境变量spring.profiles.active设置为prod，这个接口就会在Swagger文档中隐藏；其他环境（比如dev、qa）下则正常展示。

方案二：通过Docket配置批量过滤私有API（适合大量私有接口） #

如果你的私有API数量较多，逐个加注解太麻烦，可以自定义一个标记注解，然后在Swagger的Docket配置中根据环境批量过滤：

步骤1：定义私有API标记注解 #

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface PrivateApi {
}

步骤2：在控制器中标记私有API #

@RestController
public class MyController {

    @PrivateApi
    @GetMapping("/private-api-1")
    public ResponseEntity<String> privateApi1() {
        return ResponseEntity.ok("私有内容1");
    }

    @PrivateApi
    @GetMapping("/private-api-2")
    public ResponseEntity<String> privateApi2() {
        return ResponseEntity.ok("私有内容2");
    }
}

步骤3：配置Docket根据环境过滤 #

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Autowired
    private Environment environment;

    @Bean
    public Docket api() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.your.package.controller"));

        // 判断当前是否为生产环境，是的话排除所有带@PrivateApi的接口
        boolean isProdEnv = Arrays.asList(environment.getActiveProfiles()).contains("prod");
        if (isProdEnv) {
            docket = docket.apis(not(RequestHandlerSelectors.withMethodAnnotation(PrivateApi.class)));
        }

        return docket.paths(PathSelectors.any())
                .build();
    }
}

这种方式的好处是可以统一管理私有API的过滤规则，后续新增私有接口只需要加@PrivateApi注解即可，无需修改配置。

方案三：自定义条件化的@ApiIgnore注解（适配原有@ApiIgnore习惯） #

如果你习惯用@ApiIgnore，可以自定义一个仅在生产环境生效的注解，结合Spring的条件注解来控制：

步骤1：自定义条件化注解 #

@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@ApiIgnore
@Conditional(ProdEnvironmentCondition.class)
public @interface ProdOnlyApiIgnore {
}

步骤2：编写环境判断条件类 #

public class ProdEnvironmentCondition implements Condition {
    @Override
    public boolean matches(ConditionContext context, AnnotatedTypeMetadata metadata) {
        // 判断当前激活的环境是否为生产
        return Arrays.asList(context.getEnvironment().getActiveProfiles()).contains("prod");
    }
}

步骤3：在控制器中使用 #

@RestController
public class MyController {

    @ProdOnlyApiIgnore
    @GetMapping("/private-api")
    public ResponseEntity<String> privateApi() {
        return ResponseEntity.ok("私有内容");
    }
}

这个注解只有在生产环境下才会被Spring识别为@ApiIgnore，从而隐藏接口；非生产环境下，该注解不生效，接口正常展示。

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