[Springboot] swagger 사용하기- 의존성 추가 및 jwt 인증 추가하기

 

Swagger는 API 개발을 위한 프레임워크로서, API 문서를 작성하고 관리하는 데 사용된다.
RESTful API를 문서화하고 API를 시각적으로 표현할 수 있다.

의존성 추가

Swagger에는
springfox와 springdoc 두가지 버전이 있다.

implementation 'io.springfox:springfox-boot-starter:3.0.0' 

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2'

하지만 springfox 사용시 Spring Boot 2.5.x 버전 이후부터는 Spring과 Swagger 사이의 버전 호환이 되지 않아 오류가 발생한다.

그래서 나는 springdoc을 사용했다.

swaggerConfig를 이용해 여러가지 설정을 해줄 수 있지만 그냥
http://~/swagger-ui.html 로 접속해도 별다른 설정없이 사용할 수 있다.

---

SwaggerConfig.java 설정

JWT사용 시 인증을 위한 authorize 설정 ( spring doc 버전 사용)

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 org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI openAPI() {

        Info info = new Info()
                .version("v1.0.0")
                .title("API TEST")
                .description("연습용");

        // SecuritySecheme명
        String jwtSchemeName = "jwtAuth";
        // API 요청헤더에 인증정보 포함
        SecurityRequirement securityRequirement = new SecurityRequirement().addList(jwtSchemeName);
        // SecuritySchemes 등록
        Components components = new Components()
                .addSecuritySchemes(jwtSchemeName, new SecurityScheme()
                        .name(jwtSchemeName)
                        .type(SecurityScheme.Type.HTTP) // HTTP 방식
                        .scheme("bearer")
                        .bearerFormat("JWT")); // 토큰 형식을 지정하는 임의의 문자(Optional)

        return new OpenAPI()
                .info(info)
                .addSecurityItem(securityRequirement)
                .components(components);
    }
}

 

위와 같이 설정 하면 swagger페이지 오른쪽 상단에 authorize버튼이 생긴다. 생성된 토큰을 입력해주면 인증을 통해 api를 호출할 수 있다.

 

버튼 클릭 후 발급받은 토큰을 입력하면 api 호출 시 헤더에 authorization이 세팅된다.