[Spring] Swagger에 대해 알아보자.

Swagger란?

공식사이트 : https://swagger.io/
swagger는 Rest API 서비스를 편리하게 무서화 해주고, 이를 통해 관리와 제 3자가 편리하게 API를 호출하고 테스트할 수 있게 도와주는 프로젝트이다. Rest 웹 서비스를 설계, 빌드, 문서화, 소비하는 일을 도와주는 대형 도구 생태계의 지원을 받는 오픈 소스 소프트웨어 프레임워크로, API 정보를 현행화하고, API를 통해 Parameter, 응답 정보, 예제 등 Spec 정보 전달이 용이하다. 실제 사용되는 Parameter로 테스트가 가능하다.

위와 같이 swagger를 적용하면 controller에 설정된 URL 리스트들의 목록을 바로 확인할 수 있고, API 기능 명세와 기능 테스트를 할 수 있다.

사용법

1. 의존성 추가

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

2. Spring Boot에 설정하기: @OpenAPIDefinition

@OpenAPIDefinition(
        info = @Info(title = "User-Service API 명세서",
                description = "사용자 어플 서비스 API 명세서",
                version = "v1"))
@Configuration
public class SwaggerConfig {

    ...
    
}

해당 swagger 페이지가 무엇을 나타내는지 알려주기 위해 info 안에 title(어떤 API 명세서를 위한 Swagger 페이지 인지), description(설명)을 작성해준다.

3. Swagger에 JWT 기능 가능하게 하기
   JWT를 가능하게 하기 위해서는 Bean 등록으로 가능하게 해주면 된다.

@OpenAPIDefinition(
        info = @Info(title = "User-Service API 명세서",
                description = "사용자 어플 서비스 API 명세서",
                version = "v1"))
@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI openAPI(){
        SecurityScheme securityScheme = new SecurityScheme()
                .type(SecurityScheme.Type.HTTP).scheme("bearer").bearerFormat("JWT")
                .in(SecurityScheme.In.HEADER).name("Authorization");
        SecurityRequirement securityRequirement = new SecurityRequirement().addList("bearerAuth");

        return new OpenAPI()
                .components(new Components().addSecuritySchemes("bearerAuth", securityScheme))
                .security(Arrays.asList(securityRequirement));
    }
    
}

해당 코드를 작성해준 후 다시 Swagger를 작동시키면 오른쪽에 있는 Authorize 버튼이 생긴다.
해당 버튼을 누르고 JWT를 입력하면 백엔드 코드에서 작성한 JWT 유효성 검증을 할 수 있고 유효성 여부에 따라 기능도 수행 여부를 결정할 수 있다.

4. Swagger JWT 인터셉터 또는 필터에 적용되지 않게 설정
   프로젝트에서 JWT로 유효성 검증을 한다면 Swagger Page는 JWT 유효성 검증이 필요 없게 해주어야 한다.

@RequiredArgsConstructor
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

    @Value("${spring.url}")
    private static String URI;

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(jwtTokenInterceptor())
                .excludePathPatterns(URI + "/swagger-resources/**", URI + "/swagger-ui/**", URI + "/v3/api-docs", URI + "/api-docs/**")
                .excludePathPatterns("/swagger-resources/**", "/swagger-ui/**", "/v3/api-docs", "/api-docs/**")
                .excludePathPatterns("/signUp", "/signIn", "/error/**", "/reissue")
                .addPathPatterns("/**");
    }

    @Bean
    public JwtTokenInterceptor jwtTokenInterceptor(){
        return new JwtTokenInterceptor(...);
    }
}

5. @Tag를 사용하여 API그룹 설정

• name: 작성한 Controller 클래스가 보여질 이름 설정
• description: 해당 API 그룹이 무엇을 나타내는지 알려준다.

@Tag(name = "Swagger 컨트롤러", description = "Swagger API입니다.")
@RequiredArgsConstructor
@RestController
public class SwaggerController {
	...
}

6. Dto에 API Data Schema 적용하기: @Schema

• description : 해당 data가 어떤 Data Schema를 나타내고자 하는 것을 명시
• nullable : null이 가능한지 아닌지 설정
• example : 해당 Data Schema 예시 값 설정

7. Controller에서 API 상세 정보 설정: @Operation

• summary : 해당 API가 무엇을 위한건지 간단하게 작성
• description : 해당 API가 무엇을 위한건지 상세하게 작성

8. API Response 설정 : @ApiResponses
   작성한 메서드가 반환하는 API Response를 작성하여 사용자가 쉽게 알아볼 수 있도록 해주는 기능이다. @ApiResponses는 여러 개의 @ApiRespons 를 반영할 수 있고 하나의 @ApiResponse는

• ResponseCode : 반환되는 Response의 상태 코드를 나타내어준다.
• description : 반환되는 상태에 따라 어떤 상태인지 결과인지를 설명해준다.
• content : 반환되는 데이터가 무엇인지 반환해준다.

이러한 기능들을 통해 Swagger를 Spring Boot에 적용하여 API를 문서화 하고 테스트를 편리하게 할 수 있다.