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 작성

com.rest.api 하위에 config package를 생성하고 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://www.daddyprogrammer.org").version("1").build();
    }
}

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

서버를 실행하고 아래 URL을 실행하면 Swagger 화면을 확인할 수 있습니다.
http://localhost:8080/swagger-ui.html

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

최신 소스는 GitHub 사이트를 참고해 주세요.
https://github.com/codej99/SpringRestApi/tree/feature/swagger

GitHub Repository를 import하여 Intellij 프로젝트를 구성하는 방법은 다음 포스팅을 참고해주세요.

Intellij에서 Github의 Spring Gradle Project import 하기

Docker로 개발 환경을 빠르게 구축하는 것도 가능합니다. 다음 블로그 내용을 읽어보세요!

Docker로 빠르게 개발환경 구성하기(mysql, redis, rabbitmq, mongoDB)

스프링 api 서버를 이용하여 웹사이트를 만들어보고 싶으시면 아래 포스팅을 참고해 주세요.

Spring Rest api + Angular framework로 웹사이트 만들기(1) – 프로젝트 구성 및 반응형 레이아웃 구현

연재글 이동

[이전글] SpringBoot2로 Rest api 만들기(3) – H2 Database 연동
[다음글] SpringBoot2로 Rest api 만들기(5) – API 인터페이스 및 결과 데이터 구조 설계