[Spring] Swagger 연동

코드의 개선 사항이 필요해보인다면 언제든 댓글로 지적해주세요 :)

Swagger를 사용하면 개발한 API들을 한 곳에 모아볼 수 있고, 테스트도 가능하다. 현재 spring-fox, spring-doc 두가지의 swagger 라이브러리가 존재하는데 이 중 spring-doc을 사용하여 연동을 진행하였다. 

구글링을 해보면 Swagger와 Springboot를 연결한 많은 사례가 존재하는데 하나의 사례만 따라하면 계속 에러가 떠서 여기저기 짜집기를 해가며 연동을 했다. 이후 다시 연동을 할 때 다시 시간 잡아먹히긴 싫으니까 기록!! 

 

build.gradle

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

---

application.yml

springdoc:
  swagger-ui:
    groups-order: DESC
    tags-sorter: alpha
    operations-sorter: method
    disable-swagger-default-url: false
    display-request-duration: true
    defaultModelsExpandDepth: 2
    defaultModelExpandDepth: 2
  show-actuator: true
  default-consumes-media-type: application/json
  default-produces-media-type: application/json
  writer-with-default-pretty-printer: true
  model-and-view-allowed: true

---

SwaggerConfig.java

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        // Security Scheme 정의
        SecurityScheme securityScheme = new SecurityScheme()
                .type(SecurityScheme.Type.HTTP)
                .scheme("bearer")
                .bearerFormat("JWT")
                .in(SecurityScheme.In.HEADER)
                .name("Authorization");

        // Security Requirement 정의
        SecurityRequirement securityRequirement = new SecurityRequirement().addList("BearerAuth");

        return new OpenAPI()
                .info(new Info().title("Lotto API")
                        .description("Lotto Application API Documentation")
                        .version("v1"))
                .addSecurityItem(securityRequirement)  // Security Requirement 추가
                .schemaRequirement("BearerAuth", securityScheme);  // Security Scheme 추가
    }
}

config 파일은 global 디렉토리에 다 몰아넣어두었다.

현재 다른 팀원이 회원 인증과 관련된 코드를 이미 작성해 둔 상태였기 때문에 swagger 내에도 인증을 요청하고 검증 받을 수 있는 로직이 필요했다. Swagger UI 상단에 Authorize 버튼을 활성화 시켜주어서 해당 입력칸에 jwt토큰을 넣어주면 된다. Swagger 자체적으로 Bearer 헤더를 붙여주기 때문에 그냥 토큰값만 넣어주면 API를 사용할 수 있다.

 

---

SecurityConfig

http.authorizeHttpRequests((auth) -> auth
                .requestMatchers("/api/auth/**").permitAll()
                .requestMatchers("/admin").hasRole("ADMIN") // ROLE_ADMIN
                .requestMatchers("/api/lotto/**").permitAll()
                .requestMatchers("/swagger-ui/**").permitAll() // Swagger UI 경로 허용
                .requestMatchers("/v3/api-docs/**").permitAll() // OpenAPI 문서 경로 허용
                .anyRequest().authenticated()
        );

이건 인증 로직 중 일부인데 해당 위치에 swagger 경로를 작성해주어야 인증 없이도 원활한 접근이 가능하다. API 중에서도 굳이 인증 없이 사용 가능한 API들은 해당 코드에 경로를 작성해주면 된다.