[Spring] Swagger 사용하기

 

배달의 민족 클론코딩을 진행할 때 API 문서를 아래와 같이 직접 스프레드시트에 작성을 했었습니다. 하지만 이 작업을 대신해 주는 Swagger 라이브러리의 존재를 알게 되었고 JDBC로 작성한 코드를 JPA로 변환하는 동시에 Swagger을 사용한 API 문서 작성을 공부해 보는 시간을 가졌습니다.

 

Swagger 의존성 추가

---

maven repository에서 Springfox Boot Starter를 찾아 build.gradle에 추가합니다.

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

의존성 추가 후, 실행을 시켰는데 아래와 같은 에러가 발생하였고 application.yml에 다음 코드를 입력하여 해결했습니다.

spring.mvc.pathmatch.matching-strategy= ant_path_matcher

프로그램 실행 후, localhost:8080/swagger-ui/로 접속하면 아래와 같은 화면이 나옵니다.

 

Swagger 설정

---

문서 제목 및 버전, 문서 설명을 추가해 보겠습니다.

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.OAS_30)
                .useDefaultResponseMessages(false) //swagger에서 제공하는 기본 응답코드(200, 401, 403, 404)를 노출하지 않음
                .apiInfo(apiInfo()) //Swagger UI로 노출할 정보
                .select()
                .apis(RequestHandlerSelectors.any()) //현재 RequestMapping으로 할당된 모든 URL 리스트를 추출
                .paths(PathSelectors.any())
                .build();
    }

    @Bean
    public ApiInfo apiInfo(){
        return new ApiInfoBuilder().version("v1.0.0").title("배달의 민족-JPA API")
                .description("JDBC를 JPA로 변환").build();
    }
}

 

Controller에서 사용

---

@Api(tags = "User Controller")
@RestController
@RequestMapping("/app/users")
@RequiredArgsConstructor
public class UserController {

    @Autowired
    private final UserProvider userProvider;
    @Autowired
    private final UserRepository userRepository;

    /**
     * 특정 회원 조회 API (프로필)
     */
    @ApiOperation(value = "회원 프로필 조회") //HTTP 메소드 설명
    @ApiResponse(code = 400, message = "BAD REQUEST") //오퍼레이션의 응답 지정
    @GetMapping("/{userId}")
    public BaseResponse<GetUserRes> getUserProfile(@ApiParam(value = "유저 ID") @PathVariable("userId") Long userId){
        GetUserRes getUserRes = userService.findUserInfo(userId);
        return new BaseResponse<>(getUserRes);
    }
}

 

@Getter @Setter
@AllArgsConstructor
public class GetUserRes {
    @ApiModelProperty(value = "유저 이름", example = "Kyko")
    private String userName;
    @ApiModelProperty(value = "유저 프로필 이미지", example = "이미지1")
    private String profileImage;
    @ApiModelProperty(value = "유저 등급", example = "고마운 분")
    private String grade;
    @ApiModelProperty(value = "유저 전번", example = "010-1111-1111")
    private String phoneNumber;
    @ApiModelProperty(value = "회원 상태", example = "JOIN")
    private UserStatus status;
    @ApiModelProperty(value = "유저 이메일", example = "kyko@naver.com")
    private String email;
    @ApiModelProperty(value = "메일 수신 여부", example = "AGREE")
    private ReceiveStatus mailReceive;
    @ApiModelProperty(value = "문자 수신 여부", example = "DISAGREE")
    private ReceiveStatus SMSReceive;
}

@ApiModelProperty를 사용하면 Example Value에 모델의 속성 데이터를 설명할 수 있습니다.

확실히 Swagger 라이브러리를 사용하면 직접 API 문서를 만드는 것보다 시간이 많이 단축되고, 파라미터를 넣어서 실제로 어떤 응답이 오는지도 테스트를 할 수 있기에 좋은 것 같습니다.

 

참고자료

---

https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter

https://bcp0109.tistory.com/326