[Spring Boot] Swagger 연동을 이용한 API 문서 자동화

목적

• API 문서 자동화

Dependency

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

Configration

package com.dh.autotrading.configuration

import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.web.bind.annotation.RestController
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
class SwaggerConfiguration{
    private val API_NAME = "Trading API"
    private val API_VERSION = "1.0"
    private val API_DESCRIPTION = "API 명세서"

    @Bean
    fun api(): Docket {
        return Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.withClassAnnotation(RestController::class.java))
            .paths(PathSelectors.any())
            .build()
            .apiInfo(apiInfo())
    }

    private fun apiInfo(): ApiInfo {
        return ApiInfoBuilder()
        .title(API_NAME)
        .description(API_DESCRIPTION)
        .version(API_VERSION)
        .build()
    }
}

1. Docket

• apiInfo: api 정보
• select: Swagger에 띄어진 엔드포인트를 제어하는 ApiSelectorBuilder의 인스턴스 반환
• apis: api 스펙이 작성되어 있는 패키지를 지정한다
• paths: apis 에 있는 API 중 특정 path를 선택. 위 코드에서는 PathSelectors.any()로 설정하여 사용자 전체 API를 지정한다.

2. apiInfo

• api의 이름, 설계 버전 등을 명시

Controller

package com.dh.autotrading.account.controller

import io.swagger.annotations.ApiOperation
import org.springframework.http.ResponseEntity
import org.springframework.web.bind.annotation.GetMapping
import org.springframework.web.bind.annotation.RequestMapping
import org.springframework.web.bind.annotation.RestController


@RestController
@RequestMapping("v1/account")
class AccountController(
) {
  @ApiOperation(value = "사용자 계좌", notes = "사용자 계좌 API")
  @GetMapping("/account_infos")
  fun getAccountInfo() =
    ResponseEntity.ok()
}

Swagger-ui

• apiInfo에 설정한 제목, 설명, 버전이 표시
• ApiOperation 어노테이션에서 등록한 내용이 Endpoint에 등록

Spring Boot 2.6 이상

• No more pattern data allowed after {*...} or ** pattern element 에러가 발생할 수 있다. ControllerHandler에 매칭시키기 위한 전략이 ant_path_matcher => path_pattern_parser 로 변경되서 생기는 에러임으로 yaml 파일에 spring.mvc.pathmatch.matching-properties값을 ant_path_matcher로 설정한다.