在生产环境中关闭 Swagger-UI

教程

1、概览

在开发环境下使用 Swagger UI 可以很方便地查看、测试 REST 服务。但是出于安全考虑，在生产环境中往往需要禁用 Swagger UI。

2、Swagger 配置

要 使用 SpringDoc 设置 Swagger，需要在配置 Bean 中对其进行定义。

创建 SwaggerConfig 类：

@Configuration
public class SwaggerConfig {
    
    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI().info(new Info().title("SpringDoc Disable SwaggerUI example")
            .description("SpringDoc Disable SwaggerUI application")
            .version("v0.0.1"));
    }
}

默认情况下，该配置 Bean 会添加到 Spring Context 中。这样，Swagger 可以在所有环境中使用。

3、使用 Spring Profile

在 Spring 中，可以使用 @Profile 注解来启用或禁用 Bean。

使用 SpEL 表达式来指定在哪些环境中激活 Swagger。

@Profile({"!prod && swagger"})

如上，在 swagger Profile，且不是 prod Profile 的情况下才会启注解的 Bean。

在配置类上添加此注解：

@Configuration 
@Profile({"!prod && swagger"})
public class SwaggerConfig {
    ...
}

现在，通过对 spring.profiles.active 属性的不同设置来启动应用，测试它是否有效：

-Dspring.profiles.active=prod // Swagger 被禁用

-Dspring.profiles.active=prod,anyOther // Swagger 被禁用

-Dspring.profiles.active=swagger // Swagger 已启用

-Dspring.profiles.active=swagger,anyOtherNotProd // Swagger 已启用

none // Swagger 被禁用

4、使用条件注解

Spring Profile 可能是一种过于粗粒度的功能切换解决方案。这种方法可能会导致配置错误和冗长、难以管理的 Profile 文件列表。

可以使用 @ConditionalOnExpression 注解作为替代方法，它允许通过自定义属性来启用 Bean：

@Configuration
@ConditionalOnExpression(value = "${useSwagger:false}")
public class SwaggerConfig {
    ...
}

如果 useSwagger 属性不存在，则默认值为 false。

可以在 application.properties（或 application.yaml）文件中设置该属性，或者在启动应用时将其设置为 VM 选项：

-DuseSwagger=true

需要注意，在生产环境中千万不要把 useSwagger 误设置为了 true。

5、总结

本文介绍了在 Spring Boot 应用中如何通过 @Profile 或 @ConditionalOnExpression 注解来在生产环境中禁用 Swagger。

Ref：https://www.baeldung.com/swagger-ui-turn-off-in-production