Linux环境下Swagger如何实现权限控制

在 Linux 环境下，Swagger（OpenAPI）的权限控制通常需结合后端框架或服务器配置实现。以下是常见的实现方案：

一、应用层面的权限控制

1. 使用框架安全模块（如 Spring Security）

场景：保护 Swagger UI 的访问路径（如 /swagger-ui.html）。

示例（Spring Boot + Spring Security）：

@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
            .authorizeRequests()
            // 允许公开访问 Swagger 资源（按需调整）
            .antMatchers("/swagger-ui/**", "/v3/api-docs/**").permitAll()
            // 对 Swagger 页面启用认证（如需要登录）
            .antMatchers("/admin/swagger-ui/**").hasRole("ADMIN")
            .anyRequest().authenticated()
            .and()
            .formLogin();
    }
}

2. 动态过滤 API 文档内容

场景：根据用户权限动态隐藏 API 接口。

示例（Spring Doc 动态生成 OpenAPI 配置）：

@Bean
public OpenApiCustomiser filterApisByRole() {
    return openApi -> openApi.getPaths().entrySet().removeIf(
        entry -> entry.getValue().readOperations().stream()
            .anyMatch(operation -> requiresAdmin(operation))
    );
}
private boolean requiresAdmin(Operation operation) {
    return operation.getSecurity().stream()
        .anyMatch(securityRequirement -> 
            securityRequirement.containsKey("admin-auth"));
}

二、反向代理层控制（Nginx/Apache）

通过服务器配置限制 Swagger 访问：

1. IP 白名单

location /swagger-ui/ {
    allow 192.168.1.0/24;  # 允许内网访问
    deny all;              # 拒绝其他IP
}

2. HTTP Basic 认证

location /swagger-ui/ {
    auth_basic "Restricted Area";
    auth_basic_user_file /etc/nginx/.htpasswd;
}

生成密码文件：htpasswd -c /etc/nginx/.htpasswd username

三、Swagger 自带的 API Key 验证

在 OpenAPI 配置中添加安全方案，要求调用时携带 API Key：

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
security:
  - ApiKeyAuth: []

用户需在 Swagger UI 中输入有效 API Key 才可测试接口。

四、生产环境建议

禁用 Swagger UI
通过环境变量控制 Swagger 仅在开发环境启用：
```
@Profile("!prod")
@Configuration
public class SwaggerConfig { ... }
```
使用 HTTPS
确保 Swagger 接口通过 HTTPS 访问，避免敏感信息泄露。