[Kotlin] SpringBoot Webflux 프로젝트에 springdoc Swagger 작성하기

build.gradle.kts

dependencies {
    implementation("org.springframework.boot:spring-boot-starter-webflux")
    implementation("org.springdoc:springdoc-openapi-starter-webflux-ui:2.0.4")
}

 

application.yml

springdoc:
  default-consumes-media-type: application/json;charset=UTF-8
  default-produces-media-type: application/json;charset=UTF-8
  swagger-ui:
    path: swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  cache:
    disabled: true

자세한 스펙은 https://springdoc.org/#properties 페이지의 5. Springdoc-openapi Properties 참고

 

 

TestController

import com.sample.test.domain.vo.UserVO
import io.swagger.v3.oas.annotations.Operation
import io.swagger.v3.oas.annotations.tags.Tag
import org.springframework.http.ResponseEntity
import org.springframework.stereotype.Controller
import org.springframework.web.bind.annotation.GetMapping
import org.springframework.web.bind.annotation.RequestMapping
import org.springframework.web.bind.annotation.RestController
import reactor.core.publisher.Mono

@RestController
@RequestMapping(value = ["/api/v1/"])
@Tag(name = "Test", description = "TEST API Document")
class TestController {
    @GetMapping("test")
    @Operation(summary = "테스트", description = "첫 번째 테스트 API")
    fun test(): Mono<ResponseEntity<UserVO>> {
        val userVO = UserVO(
            id = 1L,
            name = "테스트",
            age = 27
        )
        return Mono.just(ResponseEntity.ok().body(userVO))
    }

    @GetMapping("main")
    @Operation(summary = "메인", description = "두 번째 테스트 API")
    fun main(): Mono<ResponseEntity<UserVO>> {
        val userVO = UserVO(
            id =  2L,
            name = "메인",
            age = 26
        )
        return Mono.just(ResponseEntity.ok().body(userVO))
    }
}

 

UserVO

data class UserVO (
    val id: Long,
    val name: String,
    val age: Int
)

 

 

---

결과

 

 

 

http://localhost:8080/v3/api-docs 

{
	"openapi": "3.0.1",
	"info": {
		"title": "OpenAPI definition",
		"version": "v0"
	},
	"servers": [
		{
			"url": "http://localhost:8080",
			"description": "Generated server url"
		}
	],
	"tags": [
		{
			"name": "Test",
			"description": "TEST API Document"
		}
	],
	"paths": {
		"/api/v1/test": {
			"get": {
				"tags": [
					"Test"
				],
				"summary": "테스트",
				"description": "첫 번째 테스트 API",
				"operationId": "test",
				"responses": {
					"200": {
						"description": "OK",
						"content": {
							"*/*": {
								"schema": {
									"$ref": "#/components/schemas/UserVO"
								}
							}
						}
					}
				}
			}
		},
		"/api/v1/main": {
			"get": {
				"tags": [
					"Test"
				],
				"summary": "메인",
				"description": "두 번째 테스트 API",
				"operationId": "main",
				"responses": {
					"200": {
						"description": "OK",
						"content": {
							"*/*": {
								"schema": {
									"$ref": "#/components/schemas/UserVO"
								}
							}
						}
					}
				}
			}
		}
	},
	"components": {
		"schemas": {
			"UserVO": {
				"type": "object",
				"properties": {
					"id": {
						"type": "integer",
						"format": "int64"
					},
					"name": {
						"type": "string"
					},
					"age": {
						"type": "integer",
						"format": "int32"
					}
				}
			}
		}
	}
}