#07 Swagger

웹 개발을 하는 데에 있어서 프론트엔드를 구현하는 입장이라면, 서버에 어떻게 데이터를 보내야 하고 어떤 데이터를 받게 되는지 알고 있어야 한다.

하지만 서버를 개발하는 입장이 아니라면, 모든 컨트롤러의 url과 구조를 완벽하게 알기도 어렵고, 소통에 많은 시간이 걸릴 것이다.

Swagger는 이러한 문제를 해결하기 위해 쉽고 간편하게 서버의 컨트롤러 함수와 테스트까지 할 수 있도록 도와주는 라이브러리이다.

01. Swagger implements

먼저, build.gradle에 다음과 같이 swagger를 추가한다.

build.gradle

implementation 'io.springfox:springfox-swagger2:2.9.2'
implementation 'io.springfox:springfox-swagger-ui:2.9.2'

02. SwaggerConfig

그리고 다음과 같이 SwaggerConfig.class를 만들자.

내용은 아래 코드처럼 채우면 된다.

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("io.cloudtype.mymemory"))
                .paths(PathSelectors.any())
                .build();
    }
}

basePackage 안에 io.cloudtype.mymemory 부분을 config폴더 상위 경로로 지정해 놓으면 된다.

03. 테스트

이제 서버를 실행시키고 /swagger-ui.html로 접속해 보자.

컨트롤러별로 어떤 url이 있는지 한눈에 파악이 가능하다.

예를 들어, join을 보자. 이 컨트롤러 함수는 회원가입을 하는 역할이고, username, password, name을 받는다.

그러면 우측의 Try it out을 눌러 테스트를 해볼 수 있다.

username : asdf
password : asdfasdf123
name : asdf
로 설정하고 Execute를 누르면..

@Validated 어노테이션에 걸려 ErrorResponse 객체가 반환된 것을 볼 수 있다.

Response Body 에는 ErrorResponse 내용을 볼 수 있다.
status : 400
message : 비밀번호는 8~16자 영문 대 소문자, 숫자, 특수문자를 사용하세요.

이제 postman같은 API 테스트 프로그램도 필요 없고, URL구성도를 작성할 일도 없다.
Swagger를 사용해서 더 손쉽게 프론트 코드 작성을 해보자.

참고로 배포 후 로컬호스트가 아닐 때에는 작동하지 않는다.
일반 유저가 Swagger페이지를 보면 문제가 발생할 수 있기에 당연한 것이다.