[Spring] Swagger 적용하기

API 문서를 자동으로 생성해주는 Swagger를 Spring에서 적용하는 법을 간단하게 정리했습니다.
이전엔 Postman을 썼는데, 보기 좋게 문서화가 된다는 점에서는 Swagger가 훨씬 유용한 것 같습니다ㅎㅎ
 

1. build.gradle.kts 의 dependencies 에
springdoc 의 springdoc-openapi-starter-webmvc-ui 패키지를 추가합니다.

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

 
Sync Now해주고 조금 기다린 뒤.. application을 run합니다.
 
 

2. 아래 링크로 접속해 OpenAPI definition 화면이 뜨는지 확인합니다.

http://localhost:8080/swagger-ui/index.html
 
 
놀랍게도 끝입니다..
 
이후 Controller를 통해 작성한 REST API를 자동으로 인식해 정리해줍니다.
그리고 try it out 버튼을 눌러 요청을 보내고 응답을 확인할 수도 있습니다.


우리가 작성한 API에 맞게 global header를 설정하고 싶다면
아래와 같이 OpenAPI 클래스에 Info 를 담아 Configuration을 이용해 Bean으로 등록하면 됩니다.
Spring이 Bean을 읽을 때 Configuration을 가장 먼저 읽기 때문에 기존에 등록된 OpenAPI Bean을 재정의합니다.

import io.swagger.v3.oas.models.Components
import io.swagger.v3.oas.models.OpenAPI
import io.swagger.v3.oas.models.info.Info
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration

@Configuration
class SwaggerConfig {

    @Bean
    fun openAPI(): OpenAPI = OpenAPI()
        .components(Components())
        .info(
            Info()
                .title("Test API")
                .description("Test API schema")
                .version("1.0.0")
        )
}

 
Swagger 공식 문서에 더 다양한 예시가 있습니다.
https://springdoc.org/#how-can-i-set-a-global-header

@Bean
fun customOpenAPI(@Value("${springdoc.version}") appVersion: String): OpenAPI {
 return OpenAPI()
        .components(Components().addSecuritySchemes("basicScheme", SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("basic"))
        .addParameters("myHeader1", Parameter().in("header").schema(StringSchema()).name("myHeader1")).addHeaders("myHeader2", Header().description("myHeader2 header").schema(StringSchema())))
        .info(Info()
        .title("Petstore API")
        .version(appVersion)
        .description("This is a sample server Petstore server. You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). For this sample, you can use the api key `special-key` to test the authorization filters.")
        .termsOfService("http://swagger.io/terms/")
        .license(License().name("Apache 2.0").url("http://springdoc.org")))
}

(공식 문서의 java 예시 코드를 kotlin으로 바꿨습니다.)