Swagger ui로 REST API 테스트,문서화

REST API를 쉽게 테스트하고 문서화 할 수 있는 좋은 tool이 있다.

Swagger라는 오픈소스 tool이다.

실제 업무에서 적용해야 하는 프로젝트는 조선시대의 스프링 버전을 사용하는 프로젝트라서.. 일단 잘 되지 않았다.

(서버조차 올라가지 않는다.)

이거 해결하느라 시간을 낭비하며 스트레스 받을 바에.. '일단' 어떻게든 실행을 시키고 여러가지로 테스트를 해 보기로 했다.

세상 가장 사랑스러운 Spring-boot를 사용한다.

pom.xml에 swagger2와 swagger ui를 사용하기 위한 dependency를 설정한다.

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.2.2</version>
        </dependency>
        
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.2.2</version>
        </dependency>

Swagger Configuration을 해주기 위한 Class를 만든다. 

다양한 configuration이 가능한듯 하지만 우선은 가장 기본적인 설정으로 만족을 하자.

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

사실 이 과정에서 두가지 문제가 발생했다.

1. 이 SwaggerConfig 클래스의 위치가 spring-boot를 구동시키는 Application클래스와 다른 위치에 있으니 정상적으로 작동하지 않았다.

2. SwaggerConfig와 전혀 다른 패키지에 위치한 Class들은 탐색을 하지 못했다. 

두가지 문제는 SwaggerConfig 클래스의 설정을 조정해 주는 것으로 해결할 수 있을듯 하지만.. 우선은 연습으로 다 같은 패키지에 때려박고 테스트 해본다.

Swagger가 정상적으로 동작하는지 확인하기 위해 서버를 올리고, "http://localhost:포트/context경로/v2/api-docs"로 접근하면 json형식의 무언가를 볼 수 있을 것이다.

이제 이 가독성이 전혀 없는 json string을 예쁜 ui로 만들어 주고 테스트를 위한 각종 ui를 제공해 주는 swagger-ui로 접근해보자.

"http://localhost:포트/context경로/swagger-ui.html" 로 접근하면 나는 만든 적도 없는 깔끔한 화면이 출력된다.

이제 내 컨트롤러들을 잘 표현해 주는지를 테스트해보기 위해 간단한 컨트롤러를 하나 만들고, 다시 실행해본다.

@Api(value = "TestController")
@RestController
public class TestController {
 
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "success request")
    })
    @RequestMapping(value = "/hello", method = RequestMethod.GET)
    public ResponseEntity<?> helloGet(
            @RequestParam(value="name",required=false,defaultValue="swagger_test") String name,
            @RequestParam(value="password",required=true) String password) {
        
        Map<String, String> datas = new HashMap<>();
        datas.put("data", "name : " + name + ", password" + password);
 
        return ResponseEntity.ok(datas);
    }
}

위 컨트롤러가 Swagger-ui에 등장하고, 테스트까지 쉽게 해 볼 수 있다.