Server Plugin

Swagger UI

필수 종속성: io.ktor:ktor-server-swagger

코드 예시: json-kotlinx-openapi

네이티브 서버

Ktor는 Kotlin/Native를 지원하며 추가 런타임이나 가상 머신 없이 서버를 실행할 수 있게 합니다.

지원: ✖️

Ktor를 사용하면 기존 OpenAPI 사양을 기반으로 프로젝트에 대한 Swagger UI를 생성하고 제공할 수 있습니다. Swagger UI를 통해 API 리소스를 시각화하고 상호 작용할 수 있습니다.

다음 도구는 코드에서 OpenAPI 정의를 생성하거나 그 반대로 생성하는 데 사용할 수 있습니다.

• IntelliJ IDEA용 Ktor 플러그인은 서버 측 Ktor 애플리케이션을 위한 OpenAPI 문서 생성 기능을 제공합니다.
• OpenAPI 제너레이터는 kotlin-server 제너레이터를 사용하여 API 정의로부터 Ktor 프로젝트를 생성할 수 있도록 해줍니다. 또는 IntelliJ IDEA의 기능을 사용할 수도 있습니다.

종속성 추가

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

Gradle (Kotlin)Gradle (Groovy)Maven

Swagger UI 구성

Swagger UI를 제공하려면 swaggerFile에 배치된 OpenAPI 사양에서 렌더링된 path에 Swagger UI와 함께 GET 엔드포인트를 생성하는 swaggerUI 메서드를 호출해야 합니다.

import io.ktor.server.plugins.swagger.*

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

이 메서드는 애플리케이션 리소스에서 OpenAPI 사양을 찾으려고 시도합니다. 그렇지 않으면 java.io.File을 사용하여 파일 시스템에서 OpenAPI 사양을 읽으려고 시도합니다.

선택적으로 swaggerUI 블록 내에서 Swagger UI를 사용자 지정할 수 있습니다. 예를 들어, 다른 Swagger UI 버전을 사용하거나 사용자 지정 스타일을 적용할 수 있습니다.

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

이제 애플리케이션을 실행하고 /swagger 페이지를 열어 사용 가능한 엔드포인트를 확인하고 테스트할 수 있습니다.

CORS 구성

API가 Swagger UI와 잘 작동하도록 하려면 교차 출원 리소스 공유(CORS) 정책을 설정해야 합니다. 아래 예시는 다음 CORS 구성을 적용합니다.

• anyHost는 모든 호스트의 교차 출원 요청을 활성화합니다.
• allowHeader는 콘텐츠 협상에 사용되는 Content-Type 클라이언트 헤더를 허용합니다.

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