kotlin + Springboot Swagger 적용하기

백앤드 서버의 API를 편하게 문서화 할 수 있는 툴들이 제공된다.

JavaDoc과 같은 툴들이 기본적이지만,

좀 더 예쁜 UI를 제공하고, 실제로 API를 사용하게 도와주는 swagger ui가 많이 사용된다.

springboot + kotlin에 swagger를 적용해본다.

 

/ 기본 구성 /

SDK 17

springboot 3.1.4

kotlin

 

예전에는 springfox를 기반으로 한 swagger가 제공되었다. 하지만 2020년 이후로 더이상 버전업이 이루어지지 않고 있다.

여기서는 springdoc을 기반으로 해서 swagger를 적용한다.

 

build.gradle.kt 의 dependencies 추가

dependencies {
	...
	implementation("org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2")
}

 

application.yml 추가

springdoc:
  packages-to-scan: com.스캔할.패키지.패스를지정합니다
  default-consumes-media-type: application/json;charset=UTF-8
  default-produces-media-type: application/json;charset=UTF-8
  swagger-ui:
    path: /peynman // 스캔된 패키지 안의 API들을 볼 디폴트로 사용할 swagger path
    disable-swagger-default-url: true
    display-request-duration: true
    operations-sorter: alpha

packages-to-scan에 swagger에 보였으면 하는 API들이 있는 패키지를 적는다.

패키지 스캔이 이루어진 곳에 있는 컨트롤러에 대해서만 swagger에 표출된다.

swagger에 표출하고 싶지 않은 controller가 있다면, 해당 controller에 @Hidden을 추가하여 원하는 동작을 할 수 있다.

 

Contoller 작성

@RestController
@RequestMapping("/memo")
@Tag(name = "예제 API", description = "Swagger 테스트용 API")
class MemoController(private val memoService: MemoService) {
    @PostMapping("/post")
    @Operation(summary = "테스트")
    fun postTestMemo(): String{
        return memoService.postTestMemo()
    }
}

@Tag 를 사용하면 해당 클래스 안의 API들을 하나로 묶을 수 있다.

@Operation 을 사용하면 해당 API에 대한 부가적인 설명을 넣을 수 있다. 추가적으로 summary 외에도 description을 적어 자세한 설명 또한 가능하다.

 

이렇게 한 후

localhost:8080/peynman 으로 접속하면

 

이렇게 예쁜 문서를 확인할 수 있다.