Server Plugin

Swagger UI

필수 의존성: io.ktor:ktor-server-swagger

코드 예제: json-kotlinx-openapi

Native 서버

Ktor supports Kotlin/Native and allows you to run a server without an additional runtime or virtual machine.

지원: ✖️

Ktor를 사용하면 OpenAPI 명세를 기반으로 프로젝트의 Swagger UI를 생성하고 제공할 수 있습니다. Swagger UI를 통해 브라우저에서 직접 API 엔드포인트를 시각화하고 상호작용할 수 있습니다.

다음과 같은 방법 중 하나로 OpenAPI 명세를 제공할 수 있습니다:

• 기존 YAML 또는 JSON 파일 제공.
• OpenAPI 컴파일러 익스텐션 및 런타임 API를 사용하여 런타임에 명세 생성.

의존성 추가

Swagger UI를 제공하려면 빌드 스크립트에 ktor-server-swagger 아티팩트를 추가해야 합니다:

Gradle (Kotlin)Gradle (Groovy)Maven

Ktor 3.4.0에서 SwaggerUI 플러그인은 ktor-server-routing-openapi 의존성을 필요로 합니다. 이는 의도적인 하위 호환성 단절(breaking change)이 아니었으며 Ktor 3.4.1에서 수정될 예정입니다. 런타임 오류를 방지하려면 Ktor 3.4.0을 사용하는 경우 의존성을 수동으로 추가하십시오.

정적 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 구성

예를 들어 커스텀 Swagger UI 버전을 지정하는 등 swaggerUI {} 블록 내에서 Swagger UI를 구성할 수 있습니다:

routing {
    swaggerUI(path = "swagger", swaggerFile = "openapi/documentation.yaml") {
        version = "4.15.5"
    }
}

CORS 구성

Swagger UI가 API 엔드포인트에 올바르게 액세스할 수 있도록 하려면 먼저 교차 출처 리소스 공유(CORS)를 구성해야 합니다.

아래 예제는 다음 CORS 구성을 적용합니다:

• anyHost는 모든 호스트로부터의 교차 출처 요청을 허용합니다.
• allowHeader는 콘텐츠 협상(content negotiation)에 사용되는 Content-Type 클라이언트 헤더를 허용합니다.

install(CORS) {
    anyHost()
    allowHeader(HttpHeaders.ContentType)
}