Swagger 기본 사용법

Swagger

Swagger 란?

• REST API 개발시 문서를 자동으로 만들어주는 프레임워크
• 간단한 설정으로 프로젝트에 지정한 URL들을 HTML 화면으로 확인
• Postman과 같이 API테스트 가능

사용법

• 라이브러리 추가
• SwaggerConfig 파일 설정

@OpenAPIDefinition(
        info = @Info(title = "타이틀",
                description = "프로젝트 설명",
                version = "v1"))
@RequiredArgsConstructor
@Configuration
public class SwaggerConfig {

    @Bean
    public GroupedOpenApi chatOpenApi() {
        String[] paths = {"/**"};

        return GroupedOpenApi.builder()
                .group("그룹명")
                .pathsToMatch(paths)
                .build();
    }
}

> Config파일을 설정후에 localhost:8080/sagger-ui/index.html 로 접속하면 아래와 같이 뜬다.

 

API 설명 추가

• Controller 위에 @Tag를 추가하면 설명을 넣을수 있다.

@Tag(name = "유저")

해당 태그 추가를 하면 아래와 같이 보기 좋게 바뀐다.

수정전

 

수정후

 

 

• @Operation Annotation으로 메서드에 대한 설명 추가 

컨트롤러 안의 메소드 위에 @Operation 어노테이션을 사용하여 설명 추가 가능

@Operation(summary = "회원가입 요청 API" ,description = "회원가입 API")
@PostMapping("/sign-up")
public ResponseEntity<?> signUp(@Validated UserRequestDto.SignUp signUp, Errors errors) {
    // validation check
    if (errors.hasErrors()) {
        return response.invalidFields(Helper.refineErrors(errors));
    }
    return userService.signUp(signUp);
}

 

수정전

수정 후