[Kotlin/Spring Boot] Swagger 에서 JWT 사용해보자

개발 환경

• spring boot 3.2
• java 21 

---

스웨거 세팅하기

• build.gradle.kts에 밑 디펜던시 추가

implementation("org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0")
implementation("org.springdoc:springdoc-openapi-starter-webmvc-api:2.2.0")

• application.yml 스웨거 관련 옵션 추가

springdoc:
  swagger-ui:
    path: /webtoon-api  // 스웨거 접근 경로
    disable-swagger-default-url: true // 스웨거 기본 url 비활성화

• 스웨거 관련 config 파일 추가

package rlc.webtoon.api.config


import io.swagger.v3.oas.annotations.OpenAPIDefinition
import io.swagger.v3.oas.models.Components
import io.swagger.v3.oas.models.OpenAPI
import io.swagger.v3.oas.models.info.Info
import io.swagger.v3.oas.models.security.SecurityRequirement
import io.swagger.v3.oas.models.security.SecurityScheme
import io.swagger.v3.oas.models.security.SecurityScheme.Type
import io.swagger.v3.oas.models.servers.Server
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer

@Configuration
@OpenAPIDefinition(
        info = io.swagger.v3.oas.annotations.info.Info(
                title = "Webtoon API",
                version = "1.0",
        )
)
class SwaggerConfig : WebMvcConfigurer {

    @Bean
    fun openAPI(): OpenAPI {

        return OpenAPI()
                .addSecurityItem(
                        SecurityRequirement().addList("Bearer Authentication")
                )
                .components(
                        Components().addSecuritySchemes
                        ("Bearer Authentication", createAPIKeyScheme())
                )
                .addServersItem(Server().url("/"))
                .info(
                        Info().title("WEBTOON API")
                                .description("Webtoon API Spec")
                                .version("v1.0.0")
                )
    }

    fun createAPIKeyScheme(): SecurityScheme? {
        return SecurityScheme().type(Type.HTTP)
                .bearerFormat("JWT")
                .scheme("bearer")
    }
}

 

• 샘플 컨트롤러 생성

@Tag(name = "인증")
@RestController
@RequestMapping("/auth")
class AuthController(
        private val authService: AuthService
) {
    @PostMapping("/login")
    @Operation(summary = "로그인")
    fun login(@RequestBody request: LoginRequest): ApiResponse<LoginResponse> {
        return ApiResponse(authService.login(request))
    }
}

 

---

스웨거 확인하기

• http://localhost:8080/webtoon-api   로 접근하면 밑과 같이 보인다. SwaggerConfig에  createAPIKeyScheme()함수를 사용해서 밑과같이 Authorize 초록색 버튼이 생겼다. 해당 버튼 클릭 후 JWT를 등록 후 API 통신하면 된다. JWT를 처리하는 로직은 인터셉터나 스프링 시큐리티를 통해 구현하면 된다.