REST API를 쉽게 테스트하고 문서화 할 수 있는 좋은 tool이 있다.
Swagger라는 오픈소스 tool이다.
실제 업무에서 적용해야 하는 프로젝트는 조선시대의 스프링 버전을 사용하는 프로젝트라서.. 일단 잘 되지 않았다.
(서버조차 올라가지 않는다.)
이거 해결하느라 시간을 낭비하며 스트레스 받을 바에.. '일단' 어떻게든 실행을 시키고 여러가지로 테스트를 해 보기로 했다.
세상 가장 사랑스러운 Spring-boot를 사용한다.
pom.xml에 swagger2와 swagger ui를 사용하기 위한 dependency를 설정한다.
1 2 3 4 5 6 7 8 9 10 11 | <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> | cs |
Swagger Configuration을 해주기 위한 Class를 만든다.
다양한 configuration이 가능한듯 하지만 우선은 가장 기본적인 설정으로 만족을 하자.
1 2 3 4 5 6 7 8 9 10 11 12 13 | @Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.any()) .paths(PathSelectors.any()) .build(); } } | cs |
사실 이 과정에서 두가지 문제가 발생했다.
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" 로 접근하면 나는 만든 적도 없는 깔끔한 화면이 출력된다.
이제 내 컨트롤러들을 잘 표현해 주는지를 테스트해보기 위해 간단한 컨트롤러를 하나 만들고, 다시 실행해본다.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | @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); } } | cs |
위 컨트롤러가 Swagger-ui에 등장하고, 테스트까지 쉽게 해 볼 수 있다.