스프링 Swagger 구현 방법

배경

스프링에서도 몇가지 설정만하면 쉽게 Swagger를 사용할 수 있음

 

개념

• 정의: 개발자가 API 문서를 쉽게 작성할 수 있도록 도와주는 오픈 소스 SW 프레임워크
• 목적:
  • API 소비자가 빠르게 API를 이해하고 사용할 수 있게 하고,
  • 손쉽게 실제 API 요청을 테스트하고 결과를 볼 수 있음
• 장점:
  • 표준화된 API 문서: 자동으로 표준화된 API 문서를 생성
  • 시각적 편집기(UI): Swagger UI를 통해 API를 시각적으로 볼 수 있음

 

구현 순서 요약

1. 의존성 추가
2. 설정파일(Config) 추가
3. 컨트롤러에서 애너테이션 사용
4. +) 스프링 시큐리티 사용시 접근 권한 설정

 

1. 의존성 추가

build.gradle에 아래 의존성 추가

//swagger
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.4'

 

 

2. 설정파일(Config) 추가

config패키지에 SwaggerConfig 클래스 추가

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI openAPI() {
        final String securitySchemeName = "bearerAuth";

        return new OpenAPI()
                .info(new Info().title("pagona")
                        .description("palgona api docs")
                        .version("v0.0.1")
                        .license(new License().name("Apache 2.0").url("http://localhost:8080")))
                .addSecurityItem(new SecurityRequirement().addList(securitySchemeName))
                .components(new Components()
                        .addSecuritySchemes(securitySchemeName, new SecurityScheme()
                                .name(securitySchemeName)
                                .type(SecurityScheme.Type.HTTP)
                                .scheme("bearer")
                                .bearerFormat("JWT")));
    }
}

 

 

3. 컨트롤러에서 애너테이션 사용

• 컨트롤러 메서드에 @Operation 애너테이션으로 API 문서를 작성한다.
  • summary = "API 제목"
  • description="API에 대한 설명"

@PostMapping()
@Operation(summary = "상품 등록 api", description = "상품 정보와 상품 사진들을 받아서 상품 등록을 진행한다.")
public ResponseEntity<Void> createProduct(
        @RequestPart(value = "productReq") ProductCreateRequest request
){

    return ResponseEntity.ok()
            .build();
}

 

 

+ 스프링 시큐리티 사용시 접근 권한 설정

• 스프링 시큐리티 사용시 Swagger 경로에 접근 권한 설정을 하지 않으면, Swagger에 오류가 발생한다.
• 따라서, 아래 2개의 경로를 열어줘야 정상적으로 작동한다.
  • /v3/**
  • swagger-ui/**

@EnableWebSecurity
@Configuration
@RequiredArgsConstructor
public class SecurityConfig {
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
                .csrf(AbstractHttpConfigurer::disable)
                .formLogin(AbstractHttpConfigurer::disable)
                .httpBasic(AbstractHttpConfigurer::disable)
                .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
                .authorizeHttpRequests(auth -> auth
                        .requestMatchers("/v3/**", "swagger-ui/**").permitAll()
                        .anyRequest().authenticated());

        return http.build();
    }
}

 

 

결과 확인

~/swagger-ui/index.html로 접근을 해보면 정상적으로 결과를 확인할 수 있다.