[ASP.NET Core] Swagger UI에 JWT 인증(Authorize) 추가하기

Swagger UI에서 Authorize 버튼으로 Bearer 토큰을 넣어 테스트하는 설정입니다.

절차

1. 패키지 설치
2. 보안 스키마 등록
3. UI에서 토큰 입력
4. 자주 하는 실수

 

1. 패키지

dotnet add package Swashbuckle.AspNetCore

2. 보안 스키마 등록

builder.Services.AddSwaggerGen(o =>
{
    o.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
    {
        Name = "Authorization",
        Type = SecuritySchemeType.Http,
        Scheme = "bearer",
        BearerFormat = "JWT",
        In = ParameterLocation.Header
    });

    o.AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference
                {
                    Type = ReferenceType.SecurityScheme,
                    Id = "Bearer"
                }
            },
            Array.Empty<string>()
        }
    });
});

3. UI에서 토큰 입력

앱을 실행하고 /swagger를 열면 상단에 Authorize 버튼이 생깁니다. 여기에 토큰 값만 넣으면 이후 요청에 Authorization: Bearer ... 헤더가 자동으로 붙습니다.

4. 자주 하는 실수

1. Bearer를 직접 붙여 Bearer Bearer ...가 됨 — 값만 넣어야 합니다
2. 스킴은 Http + bearer 조합이어야 입력창이 뜹니다(ApiKey면 헤더 이름만 입력)
3. 토큰 만료 후 401이 나면 다시 발급해야 합니다
4. 운영에서는 Swagger UI 노출을 막습니다

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

정리

1. AddSecurityDefinition으로 Bearer 스킴 등록
2. 토큰은 값만 입력
3. 운영에서는 UI 노출을 막는다