Swagger API 문서 자동화 적용

코드 분석 중에 @Api 라는 어노테이션을 보고 어떤 건지 궁금하던 중 swagger에 사용한다는 것을 알게 되었다.

REST API 애플리케이션 개발에 있어 API 스펙에 대한 문서작업은 많은 시간을 요구한다.
또한 운영을 하게 되면서 지속적으로 문서를 업데이트 하는 것 또한 많은 리소스가 필요하다.

이러한 시간을 단축시키기 위해 문서 자동화 프레임 워크를 이용하는 방법이 있다.
대표적으로 Swagger, Spring REST Docs가 있는데 그 중 Swagger 적용 방법에 대해 알아본다.

흐름

1️⃣ Dependency 설정

2️⃣ SwaggerConfig : Swagger 관련된 설정

3️⃣ Swagger 어노테이션 적용

1. Dependency 설정

Maven

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

Gradle

// https://mvnrepository.com/artifact/io.springfox/springfox-swagger2
compile group: 'io.springfox', name: 'springfox-swagger2', version: '2.9.2'

// https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui
compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.9.2'

2. SwaggerConfig

@EnableSwagger2 어노테이션을 추가하여 Swagger 관련된 설정을 추가

package kr.co.sample.sampleapi.common.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    private ApiInfo commonInfo() {
        return new ApiInfoBuilder()
                .title("USER API")
                //.description("")
                //.license("leeys")
                //.licenseUrl("http://leeys.tistory.com")
                .version("1.0")
                .build();
    }

    @Bean
    public Docket allApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("USER")
                .useDefaultResponseMessages(false)
                .select()
                //.apis(RequestHandlerSelectors.any())
                .apis(RequestHandlerSelectors.basePackage("kr.co.sample.sampleapi.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(commonInfo());
    }
}

3. Swagger 어노테이션 적용

Swgger 사용을 위한 설정을 완료한 후 Controller에 해당 API에 대한 내용을 Swagger 어노테이션을 사용하여 작성해주면 자동으로 추가된다.

추가 어노테이션 정보는 Swagger GitHub 에서 확인 가능하다.

어노테이션	설명
@Api	클래스를 Swagger 리소스 대상으로 표시
@ ApiOperation	요청 URL에 매핑된 API에 대한 설명
@ApiParam	요청 Parameter에 대한 설명 및 필수여부, 예제값 설정
@ApiResponse	응답에 대한 설명

Controller

package kr.co.sample.sampleapi.controller;

import io.swagger.annotations.ApiOperation;
import kr.co.sample.sampleapi.entity.User;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.*;

@RestController
public class TestController {
    @ApiOperation(value = "사용자 정보 조회", notes = "UserId를 이용하여 사용자 정보를 조회합니다.")
    @GetMapping(value = "/users/{id}", produces = MediaType.APPLICATION_JSON_VALUE)
    public Object findUser(
            @ApiParam(value = "user id", required = true, example = "1")
            @PathVariable(value = "id", required = true) String id,
            @ApiParam(value = "User Agent Type ", required = true, example = "Mozila")
            @RequestHeader(value = "User-Agent") String userAgent,
            @ApiParam(value = "parameter1 ", required = false)
            @RequestParam(value = "param1", required = false) String param1,
            @ApiParam(value = "parameter2 ", required = false)
            @RequestParam(value = "param2", required = false) String param2){

        return true;
    }

    @ApiOperation(value = "사용자 리스트 조회", notes = "특정 조건에 맞는 사용자 리스트를 조회합니다.")
    @GetMapping(value = "/users", produces = MediaType.APPLICATION_JSON_VALUE)
    public Object findUsers(
            @RequestHeader(value = "User-Agent") String userAgent,
            @ModelAttribute User user){

        return true;
    }

    @ApiOperation(value = "사용자 생성", notes = "신규 사용자를 생성합니다.")
    @PostMapping(value = "/users", produces = MediaType.APPLICATION_JSON_VALUE)
    public Object CreateUser(
            @RequestHeader(value = "User-Agent") String userAgent,
            @RequestBody(required = true) User user){

        return true;
    }
}

User Model

package kr.co.sample.sampleapi.entity;

import io.swagger.annotations.ApiParam;
import lombok.Data;

@Data
public class User {
    @ApiParam(value = "사용자 이름", required = false, example = "홍길동")
    private String userName;
    @ApiParam(value = "휴대폰 번호", required = false, example = "010-0000-0000")
    private String phoneNumber;
}

http://localhost:8080/swagger-ui.html 로 접속하여 추가된 API를 확인한다.