Swagger UI
필수 의존성: io.ktor:ktor-server-swagger
코드 예제: json-kotlinx-openapi
Native 서버Ktor는 Kotlin/Native를 지원하므로 추가 런타임이나 가상 머신 없이도 서버를 실행할 수 있습니다. 지원: ✖️
Ktor를 사용하면 OpenAPI 사양(specification)을 기반으로 프로젝트의 Swagger UI를 생성하고 제공(serve)할 수 있습니다. Swagger UI를 통해 브라우저에서 직접 API 엔드포인트를 시각화하고 상호작용할 수 있습니다.
OpenAPI 사양은 다음 방법 중 하나로 제공할 수 있습니다:
의존성 추가
Swagger UI를 제공하려면 빌드 스크립트에 ktor-server-swagger 아티팩트를 추가해야 합니다:
implementation(ktorLibs.server.swagger)implementation ktorLibs.server.swagger<dependency>
<groupId>io.ktor</groupId>
<artifactId>ktor-server-swagger-jvm</artifactId>
<version>${ktor_version}</version>
</dependency>정적 OpenAPI 파일 사용
기존 OpenAPI 사양 파일로부터 Swagger UI를 제공하려면 swaggerUI() 함수를 사용하고 파일 위치를 지정합니다.
다음 예제는 swagger 경로에 GET 엔드포인트를 생성하고 제공된 OpenAPI 사양 파일로부터 Swagger UI를 렌더링합니다:
import io.ktor.server.plugins.swagger.*
// ...
routing {
swaggerUI(path = "swagger", swaggerFile = "openapi/documentation.yaml")
}플러그인은 먼저 애플리케이션 리소스에서 사양을 찾습니다. 찾지 못한 경우, java.io.File을 사용하여 파일 시스템에서 로드하려고 시도합니다.
런타임 OpenAPI 메타데이터 생성
정적 파일에 의존하는 대신 OpenAPI 컴파일러 플러그인과 라우트 어노테이션에서 생성된 메타데이터를 사용하여 런타임에 OpenAPI 사양을 생성할 수 있습니다:
swaggerUI("/swaggerUI") {
info = OpenApiInfo("My API", "1.0")
source = OpenApiDocSource.Routing(ContentType.Application.Json) {
routingRoot.descendants()
}
}이를 통해 애플리케이션의 현재 상태를 반영하는 생성된 OpenAPI 문서를 /swaggerUI 경로에서 접근할 수 있습니다.
OpenAPI 컴파일러 확장 및 런타임 API에 대한 자세한 내용은 OpenAPI 사양 생성을 참조하세요.
Swagger UI 구성
swaggerUI {} 구성 블록을 사용하면 OpenAPI 문서를 구성하고 Swagger UI를 커스터마이징할 수 있습니다.
문서 메타데이터 구성
구성 블록에서 최상위 OpenAPI 메타데이터를 직접 정의할 수 있습니다.
예를 들어 일반적인 API 정보를 지정하려면 info를 사용하고, 태그와 해당 설명을 정의하려면 tag()를 사용합니다:
swaggerUI("/swagger") {
info = OpenApiInfo("Books API from routes", "1.0.0")
tag(
name = "Books",
description = "Operations on books"
)
}또한 서버, 보안 요구 사항, 재사용 가능한 컴포넌트, 외부 문서 및 사양 확장과 같은 기타 최상위 OpenAPI 속성도 구성할 수 있습니다.
사용 가능한 전체 옵션 목록은 SwaggerConfig API 레퍼런스를 참조하세요.
Swagger UI 버전 구성
기본적으로 Ktor는 사전 정의된 Swagger UI 버전을 사용합니다. 다른 버전을 사용하려면 version 속성을 설정하세요:
routing {
swaggerUI(path = "swagger", swaggerFile = "openapi/documentation.yaml") {
version = "5.31.0"
}
}OpenAPI 3.1.x 문서에는 Swagger UI 5.x가 필요하며, Swagger UI 4.x는 OpenAPI 3.0.x만 지원합니다.
CORS 구성
Swagger UI가 API 엔드포인트에 올바르게 접근할 수 있도록 하려면 먼저 교차 출처 리소스 공유(CORS, Cross-Origin Resource Sharing)를 구성해야 합니다.
아래 예제는 다음과 같은 CORS 구성을 적용합니다:
anyHost는 모든 호스트에서의 교차 출처 요청을 허용합니다.allowHeader는 콘텐츠 협상(Content Negotiation)에 사용되는Content-Type클라이언트 헤더를 허용합니다.
install(CORS) {
anyHost()
allowHeader(HttpHeaders.ContentType)
}