[Spring Boot] Swagger API 문서 자동화

1. Swagger

1) Swagger 란?

개발자가 REST 웹 서비스를 설계, 빌드, 문서화, 소비하는 일을 도와주는 대형 도구 생태계의 지원을 받는 오픈 소스 소프트웨어 프레임워크이다.

2) 의존성 추가

springfox-boot-starter의 경우 Swagger로 API 문서를 제작할 수 있도록 도와주며 , springfox-swagger-ui의 경우 시각화에 도움을 준다.

implementation 'io.springfox:springfox-boot-starter:3.0.0' // 문서
implementation 'io.springfox:springfox-swagger-ui:3.0.0' // UI 제공

3) SwaggerConfig.java

- Docket

Springfox 프레임워크의 기본 인터페이스가 될 빌더로 구성을 위한 여러 가지 기본값과 편리한 방법을 제공한다. select()로 ApiSelectorBuilder를 반환받아 사용할 수 있도록 해준다.

- apis

특정 위치의 API들을 가져올 것인가에 대한 정의이다. RequestHandlerSelectors.any()일 경우 Spring Boot에서 기본적으로 제공하는 basic-error-controller 도 API 문서로 만들어지는 것을 확인할 수 있다.

 

특정 패키지만을 적용하는 경우에는 RequestHandlerSelectors.basePackage("com.example.demo.api")와 같은 형식으로 지정하면 해당 패키지 하위에 있는 Controller 기준으로 만들어준다.

- paths

특정 path만 필터링하여 문서를 만들어 준다.

- useDefaultResponseMessages

기본 HTTP 응답 코드를 사용해야 하는지를 나타내는 플래그이다.

@EnableSwagger2
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any()) // PathSelectors.ant("/api/**")
                .build();
    }
}

---

- 응용

package com.example.demo.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.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@EnableSwagger2
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("Test API")
                .apiInfo(new ApiInfoBuilder()
                        .title("사칙연산 API")
                        .description("스웨거를 활용한 API문서")
                        .version("1.0.0")
                        .termsOfServiceUrl("https://ozofweird.tistory.com") // 서비스 약관
                        .contact(new Contact(
                                "ozofweird",
                                "https://ozofweird.tistory.com",
                                "ozofweird@test.com")
                        )
                        .build()
                )
                .useDefaultResponseMessages(false)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }
}

- 예시 Controller

package com.example.demo.controller;

import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

@RestController
public class TestController {

    @ApiOperation(value = "덧셈", notes = "num1 과 num2 를 더합니다.")
    @GetMapping(value = "/addition")
    public Integer addition(Integer num1, Integer num2) {
        return num1 + num2;
    }

    @ApiOperation(value = "뺄셈", notes = "num1 에서 num2 를 뺍니다.")
    @PostMapping(value = "/subtraction")
    public Integer subtraction(Integer num1, Integer num2) {
        return num1 - num2;
    }

    @ApiOperation(value = "곱셈", notes = "num1 에 num2 를 곱합니다.")
    @PutMapping(value = "/multiplication")
    public Integer multiplication(Integer num1, Integer num2) {
        return num1 * num2;
    }

    @ApiOperation(value = "나눗셈", notes = "num1 에서 num2 로 나눕니다.")
    @DeleteMapping(value = "/division")
    public Integer division(Integer num1, Integer num2) {
        return num1 / num2;
    }
}

4) 접속 

localhost:8080/swagger-ui/

6) OpenAPI, SwaggerUI

OpenAPI는 Swagger 사양으로 알려져 있으며 RESTful 웹 서비스를 설명, 생성, 소비 및 시각화하기 위한 기계 판독 기능 인터페이스 파일에 대한 사양이다. 즉, API 자체를 설명하는 인터페이스 스펙이다. 만들어진 Swagger를 보면 'http://localhost:8080/v2/api-docs?group=Test%20API' 링크를 확인할 수 있는데, 이를 선택할 경우 JSON 파일을 확인할 수 있다. 

이 JSON 파일을 활용한다면 별도의 구현 로직 없이도 API 리소스를 시각화할 수 있다. 즉, 문서화가 포함되어있는 application을 별도의 서버로 띄워야 했지만, SwaggerUI를 사용하면 그럴 필요가 없어진다는 뜻이다.

 

예를 들어 A application과 B application이 있을 때, 일반적으로 A, B 각각 서버를 띄워 API 문서를 확인한다. 하지만 OpenAPI 스펙에 맞춘 문서(JSON)가 있다면, SwaggerUI가 운영되는 서버 하나로 한곳에서 모두 볼 수 있다.

---

CentOS 환경에서 아무것도 설치되어있지 않는다고 가정하에 도커에 SwaggerUI를 설치하여 확인하는 다음과 같다. 

 

우선, 사전에 home/test 하위에 api.json 파일을 만들어두고, 이미지를 띄워 서버의 80 번 포트로 접근하면 직접 서버를 띄워서 했던 것처럼 동일하게 확인할 수 있다.

# yum 최신 업데이트
sudo yum update

# docker 설치 및 시작
sudo yum install docker
sudo systemctl start docker

# swagger-ui docker 이미지 pull 
sudo docker pull swaggerapi/swagger-ui

# docker 이미지 run, 백그라운드 모드로, 
docker run -d -p 80:8080 -e SWAGGER_JSON=/mnt/api.json -v /home/test:/mnt swaggerapi/swagger-ui

 

---

[참고] springfox.github.io/springfox/docs/current/#springfox-spring-mvc-and-spring-boot

[참고] swagger.io/tools/swagger-ui/

[참고] jojoldu.tistory.com/31