SpringBoot2로 Rest api 만들기(4) – Swagger API 문서 자동화

앞서 개발한 api는 테스트를 위해 Postman을 따로 설치해야 하는 불편함이 있었습니다. 요번에 설명하려는 Swagger라는 문서 자동화 툴은 간단한 설정만으로도 테스트 가능한 Web UI를 지원하여 api를 테스트를 위해 부가적으로 서드파티 프로그램을 깔 필요가 없습니다. 또한 최소한의 작업을 통해 자동으로 API Document를 만들어주므로 클라이언트 개발자에게 문서 내용을 전달하기 위해 추가 작업을 하지 않아도 됩니다.build.gradle에 swagger 라이브러리를 추가

현재 시점 기준 Swagger는 최신 버전이 2.9.2지만 2.6.1 이상의 버전은 세팅이 잘 안되거나 Web UI가 기존 버전에 비해 매우 불편해졌습니다. 그래서 2.6.1 버전 사용을 추천합니다.

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

SwaggerConfiguration 작성

@Configuration @EnableSwagger2 public class SwaggerConfiguration {     @Bean     public Docket swaggerApi() {         return new Docket(DocumentationType.SWAGGER_2).apiInfo(swaggerInfo()).select()                 .apis(RequestHandlerSelectors.basePackage("com.rest.api.controller"))                 .paths(PathSelectors.any())                 .build()                 .useDefaultResponseMessages(false); // 기본으로 세팅되는 200,401,403,404 메시지를 표시 하지 않음     }       private ApiInfo swaggerInfo() {         return new ApiInfoBuilder().title("Spring API Documentation")                 .description("앱 개발시 사용되는 서버 API에 대한 연동 문서입니다")                 .license("happydaddy").licenseUrl("http://daddyprogrammer.org").version("1").build();     } }

com.rest.api 하위에 config package를 생성하고 SwaggerConfiguration파일을 작성합니다.
basePackage(“com.rest.api.controller”)).paths(PathSelectors.any())
com.rest.api.controlle하단의 Controller내용을 읽어 mapping 된 resource들을 문서화시킵니다.
아래와 같이 작성해서 v1으로 시작하는 resource들만 문서화시킬 수도 있습니다.
PathSelectors.ant(“/ v1/**”)
swaggerInfo를 세팅하면 문서에 대한 설명과 작성자 정보를 노출시킬 수 있습니다.

UserController 수정

package com.rest.api.controller.v1;   import com.rest.api.entity.User; import com.rest.api.repo.UserJpaRepo; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import io.swagger.annotations.ApiParam; import lombok.RequiredArgsConstructor; import org.springframework.web.bind.annotation.*;   import java.util.List;   @Api(tags = {"1. User"}) @RequiredArgsConstructor @RestController @RequestMapping(value = "/v1") public class UserController {       private final UserJpaRepo userJpaRepo;       @ApiOperation(value = "회원 조회", notes = "모든 회원을 조회한다")     @GetMapping(value = "/user")     public List<User> findAllUser() {         return userJpaRepo.findAll();     }       @ApiOperation(value = "회원 입력", notes = "회원을 입력한다.")     @PostMapping(value = "/user")     public User save(@ApiParam(value = "회원아이디", required = true) @RequestParam String uid,                      @ApiParam(value = "회원이름", required = true) @RequestParam String name) {         User user = User.builder()                 .uid(uid)                 .name(name)                 .build();         return userJpaRepo.save(user);     } }

@Api(tags = {“1. User”})
UserController를 대표하는 최상단 타이틀 영역에 표시될 값을 세팅합니다.
@ApiOperation(value = “회원 조회”, notes = “모든 회원을 조회한다”)
각각의 resource에 제목과 설명을 표시하기 위해 세팅합니다.
@ApiParam(value = “회원 이름”, required = true) @RequestParam ~~~
파라미터에 대한 설명을 보여주기 위해 세팅합니다.

Test swagger

http://localhost:8080/swagger-ui.html

com.rest.api.controller 하위의 Controller에 대해서 문서가 작성되었습니다. 문서 내용을 작성한 UserController와 작성하지 않은 HelloController에 대해서 내용이 다르게 나오는것을 확인 할수 있습니다.

항목을 누르면 실제 resource에 대한 항목이 출력됩니다. 문서 내용을 작성한 대로 표시되는 것을 확인할 수 있습니다.

GET /user항목을 클릭하면 api문서에 대한 설명과 결과 모델을 볼수 있습니다. 그리고 Try it out! 을 클릭하여 응답 결과도 확인 가능합니다.

POST /user항목을 클릭하면 Get과 동일한 포맷의 형태로 문서 내용을 확인할 수 있습니다. 요구하는 Parameter값을 세팅할 수 있도록 제공되고 Try it out을 클릭하면 자동으로 Post방식으로 서버에 요청을 보내고 결과를 볼 수 있습니다.

여기까지 SpringBoot에 swagger를 설정하는 방법을 살펴보았습니다. 실무에서는 개발 문서를 작성하고 테스트해야 하는 일이 빈번한데 위와 같이 Swagger를 사용하면 번거롭게 문서를 추가로 작업할 필요가 없을 뿐만 아니라 즉시 테스트도 가능하므로 작업에 대한 생산성을 높일 수 있게 됩니다.

최신 소스는 GitHub 사이트를 참고해 주세요. https://github.com/codej99/SpringRestApi/tree/feature/swagger
GitHub로 프로젝트 구성은 다음을 참고해주세요.
https://daddyprogrammer.org/post/1215/intellij-github-spring-gradle-project-import

 

 

[출처] https://daddyprogrammer.org/post/313/swagger-api-doc/