debian swagger如何鉴权

在 Debian 上部署的 Swagger（通常指 Swagger UI / Swagger Editor / Springdoc、Swagger2 等），“鉴权”一般分两种场景：

1. Swagger UI 本身的访问鉴权（防止别人看到你的 API 文档）
2. Swagger 中调用的接口鉴权（如 JWT、OAuth2、API Key）

下面按常见方案说明。

一、Swagger UI 本身的访问鉴权（Debian 常见做法）

方案 1：Nginx + Basic Auth（最常用）

适合：Swagger UI 由 Nginx 静态托管或通过反向代理

sudo apt install nginx apache2-utils

创建密码文件：

sudo htpasswd -c /etc/nginx/swagger_passwd admin

Nginx 配置：

server {
    listen 80;
    server_name swagger.example.com;

    location / {
        auth_basic "Swagger Auth";
        auth_basic_user_file /etc/nginx/swagger_passwd;
        proxy_pass http://127.0.0.1:8080;
    }
}

sudo nginx -t
sudo systemctl restart nginx

✅ 访问 Swagger 需要账号密码

方案 2：Spring Boot + Spring Security（后端鉴权）

适合：Springdoc / Swagger2

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/swagger-ui/**", "/v3/api-docs/**").authenticated()
                .anyRequest().permitAll()
            )
            .httpBasic(Customizer.withDefaults());
        return http.build();
    }
}

二、Swagger 中接口的鉴权配置（API 层）

1️⃣ JWT / Bearer Token

Swagger UI 加“Authorize”按钮：

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
        .components(new Components()
            .addSecuritySchemes("bearer",
                new SecurityScheme()
                    .type(SecurityScheme.Type.HTTP)
                    .scheme("bearer")
                    .bearerFormat("JWT")))
        .addSecurityItem(new SecurityRequirement().addList("bearer"));
}

2️⃣ API Key

.addSecuritySchemes("apiKey",
    new SecurityScheme()
        .type(SecurityScheme.Type.APIKEY)
        .in(SecurityScheme.In.HEADER)
        .name("X-API-KEY"))

3️⃣ OAuth2

.addSecuritySchemes("oauth2",
    new SecurityScheme()
        .type(SecurityScheme.Type.OAUTH2)
        .flows(new OAuthFlows()
            .authorizationCode(new OAuthFlow()
                .authorizationUrl("https://auth.example.com/oauth2/authorize")
                .tokenUrl("https://auth.example.com/oauth2/token"))))

三、生产环境建议（Debian）

✅ 生产环境 不要直接暴露 Swagger

• 内网访问
• Nginx IP 白名单
• 环境变量控制是否启用

Spring Boot：

springdoc:
  swagger-ui:
    enabled: false

四、常见组合推荐

如果你能告诉我：

• 用的是 Swagger UI / Springdoc / Swagger2
• 部署方式（Nginx / Docker / Spring Boot）
• 鉴权类型（Basic / JWT / OAuth2）

我可以给你 精准配置示例。