[Spring Boot] Kotlin 기반 Spring Boot 프로젝트에 Swagger 3.0.0 적용하기

본 포스트에서 사용하는 Springfox는 2020년 7월 이후로 릴리즈가 중단되었습니다. 현재도 지속적으로 릴리즈 중이면서 Swagger UI를 사용할 수 있는 또 다른 라이브러리인 Springdoc을 사용하는 방법은 이 링크를 참고해주세요.

---

목차

기본 환경

• IntelliJ Ultimate 2022.3
• Spring Boot 2.7.6
• Kotlin 1.7.21(JDK 11)
• Springfox Swagger UI 3.0.0

Swagger란?

Swagger는 개발자가 REST API를 설계, 빌드, 테스트, 문서화를 쉽게 할 수 있도록 도와주는 오픈 소스 프레임워크이다. Swagger를 사용하면 따로 Postman을 사용하지 않거나 테스트 페이지를 만들지 않고도 직접 파라미터를 입력하면서 개발한 API를 간단히 테스트해볼 수 있다. 본 포스트에서는 Spring Boot 기반의 프로젝트에 Swagger를 적용하여 API를 테스트하는 기본적인 방법에 대해 정리한다.

예시 페이지 : Swagger Live Demo

Swagger 적용

1. 의존성 목록에 Swagger 라이브러리 추가

Swagger를 사용하기 위해서는 우선 프로젝트에 관련 라이브러리를 추가해야 한다. 빌드 환경에 따라 다음 코드를 추가하고 변경사항을 다시 로드한다.

 

Gradle

implementation("io.springfox:springfox-swagger-ui:3.0.0")
implementation("io.springfox:springfox-boot-starter:3.0.0")

Maven

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

2. Swagger 기본 설정

라이브러리를 추가하였다면 Swagger 설정을 위한 클래스를 작성한다. 클래스의 이름은 원하는대로 작성해도 된다.

import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.web.servlet.config.annotation.EnableWebMvc
import springfox.documentation.builders.ApiInfoBuilder
import springfox.documentation.builders.PathSelectors
import springfox.documentation.builders.RequestHandlerSelectors
import springfox.documentation.spi.DocumentationType
import springfox.documentation.spring.web.plugins.Docket

@Configuration
@EnableWebMvc
class SwaggerConfig {
    @Bean
    fun swaggerApi(): Docket = Docket(DocumentationType.OAS_30)
        .consumes(getConsumeContentTypes())
        .produces(getProduceContentTypes())
        .apiInfo(swaggerInfo())
        .select()
        .apis(RequestHandlerSelectors.basePackage("com.colabear754.swagger_example.controllers"))
        .paths(PathSelectors.any())
        .build()
        .useDefaultResponseMessages(false)

    private fun swaggerInfo() = ApiInfoBuilder()
        .title("스웨거 테스트")
        .description("스웨거로 API를 테스트")
        .version("1.0.0")
        .build()

    private fun getConsumeContentTypes(): Set<String> {
        val consumes = HashSet<String>()
        consumes.add("multipart/form-data")
        return consumes
    }

    private fun getProduceContentTypes(): Set<String> {
        val produces = HashSet<String>()
        produces.add("application/json;charset=UTF-8")
        return produces
    }
}

• @Configuration : 설정 파일임을 선언.
• @EnableWebMvc : Swagger 3.0.0 활성화.
• Docket : Swagger 설정을 해주는 핵심 Bean. 각 설정 정보는 다음과 같다.

consumes()	Request로 보낼 수 있는 문서 타입 지정
produces()	Response로 받을 수 있는 문서 타입 지정
apiInfo()	Swagger 페이지에 표시될 기본 정보
select()	API 선택자를 생성
apis()	Swagger를 적용할 기준 패키지 선택. 위 코드에서는 'com.colabear754.swagger_example.controllers'가 해당됨
paths()	apis()로 지정된 패키지 내에서 조건에 맞는 path를 필터링 위 코드에서는 모든 path를 포함
build()	Docket 객체 생성
useDefaultResponseMessages()	Swagger 기본 응답 메시지 표시 여부

모든 설정이 끝났다면 Shift + F10을 눌러 내장 톰캣을 실행한 후 브라우저의 주소창에 'localhost:8080/swagger-ui/index.html'을 입력하여 접속하면 다음과 같은 창이 나타날 것이다.

위 코드의 swaggerInfo()의 내용들이 나타나는 것을 볼 수 있다. 현재는 작성된 API가 없기 때문에 'No operations defined in spec!'라는 문구가 뜬다. 간단한 API를 만들어서 Swagger로 만들어진 문서에 표시를 해보도록 하자.

3. Swagger 문서에 API 등록

사실 Swagger는 2번 과정만 잘 수행했다면 문서에 API를 등록하기 위해 별도의 과정을 거칠 필요가 없다. 위의 apis()에 지정된 패키지 내부의 컨트롤러에 있는 매핑된 메소드는 모두 자동으로 등록된다. 이전 단계의 config에서 설정한 패키지 내부에 예시 컨트롤러를 아래와 같이 작성하고 프로젝트를 재실행하면 아래와 같이 API가 등록되어 있는 것을 볼 수 있다.

import io.swagger.annotations.Api
import io.swagger.annotations.ApiImplicitParam
import io.swagger.annotations.ApiOperation
import org.springframework.web.bind.annotation.GetMapping
import org.springframework.web.bind.annotation.RequestMapping
import org.springframework.web.bind.annotation.RequestParam
import org.springframework.web.bind.annotation.RestController
import springfox.documentation.annotations.ApiIgnore

@Api(tags = ["예제 API"], description = "Swagger 테스트용 API")
@RestController
@RequestMapping("/")
class ExampleController {
    @ApiOperation(value = "문자열 반복", notes = "파라미터로 받은 문자열을 2번 반복합니다.")
    @ApiImplicitParam(name = "str", value = "2번 반복할 문자열")
    @GetMapping("/returnStr")
    fun returnStr(@RequestParam str: String) = "$str\n$str"

    @GetMapping("/example")
    fun example() = "예시 API"

    @ApiIgnore
    @GetMapping("/ignore")
    fun ignore() = "무시되는 API"
}

• @Api : tags에 컨트롤러를 설명할 제목을, description에 적당한 설명을 작성한다. 이 어노테이션을 생략하면 컨트롤러의 이름에 따라 자동으로 설정된다.
• @ApiOperation : value에는 API의 이름을, notes에는 API의 설명을 작성한다. 이 어노테이션을 생략하면 메소드의 이름이 API의 이름이 된다.
• @ApiImplicitParam : name에는 메소드로 보내는 파라미터의 이름을, value에는 파라미터에 대한 설명을 작성한다.
• @ApiIgnore : 이 어노테이션이 붙은 메소드나 파라미터는 Swagger 문서에 표시되지 않는다.

4. Swagger에 등록된 API 테스트

'localhost:8080/swagger-ui/index.html'에 접속하여 API를 테스트해보자. API를 테스트하려면 우측의 try it out 버튼을 누르면 텍스트 필드가 입력 가능한 상태로 바뀌고 Execute 버튼이 생기는데 텍스트 필드에 파라미터로 전달하고자 하는 값을 입력한 후 Execute 버튼을 누르면 API가 동작하게 된다.

문자열을 2번 반복하는 API가 정상적으로 동작하는 것을 볼 수 있다.