Server Plugin

OpenAPI

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

코드 예제: json-kotlinx-openapi

Native 서버

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

지원: ✖️

Ktor를 사용하면 OpenAPI 사양(specification)을 기반으로 OpenAPI 문서를 제공할 수 있습니다.

다음 방법 중 하나로 OpenAPI 사양을 제공할 수 있습니다:

• 기존 YAML 또는 JSON 파일 제공.
• OpenAPI 컴파일러 확장 및 런타임 API를 사용하여 런타임 시 사양 생성.

두 경우 모두, OpenAPI 플러그인은 서버에서 사양을 어셈블하고 문서를 HTML로 렌더링합니다.

의존성 추가

• OpenAPI 문서를 제공하려면 빌드 스크립트에 ktor-server-openapi 아티팩트를 추가해야 합니다.

  Gradle (Kotlin)Gradle (Groovy)Maven

• 필요한 경우, 코드 생성기(code generator)를 커스터마이징하려면 swagger-codegen-generators 의존성을 추가하세요.

  Gradle (Kotlin)Gradle (Groovy)Maven

  $swagger_codegen_version을 swagger-codegen-generators 아티팩트의 필요한 버전(예: 1.0.36)으로 교체할 수 있습니다.

Ktor 3.4.0에서 OpenAPI 플러그인은 ktor-server-routing-openapi 의존성을 필요로 합니다. 이는 의도된 브레이킹 체인지(breaking change)가 아니며 Ktor 3.4.1에서 수정될 예정입니다. 런타임 에러를 방지하려면 Ktor 3.4.0을 사용하는 경우 의존성을 수동으로 추가하세요.

정적 OpenAPI 파일 사용

기존 사양에서 OpenAPI 문서를 제공하려면, OpenAPI 문서 경로를 인자로 받는 openAPI() 함수를 사용하세요.

다음 예제는 openapi 경로에 GET 엔드포인트를 생성하고 제공된 OpenAPI 사양 파일로부터 Swagger UI를 렌더링합니다.

import io.ktor.server.plugins.openapi.*

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

플러그인은 먼저 애플리케이션 리소스(resources)에서 사양을 찾습니다. 찾지 못하면 java.io.File을 사용하여 파일 시스템에서 로드하려고 시도합니다.

런타임 OpenAPI 메타데이터 생성

정적 파일에 의존하는 대신, OpenAPI 컴파일러 플러그인과 라우트 어노테이션(route annotations)으로 생성된 메타데이터를 사용하여 런타임에 OpenAPI 사양을 생성할 수 있습니다.

이 모드에서 OpenAPI 플러그인은 라우팅 트리(routing tree)에서 직접 사양을 어셈블합니다.

 openAPI(path = "openapi") {
    info = OpenApiInfo("My API", "1.0")
    source = OpenApiDocSource.Routing {
        routingRoot.descendants()
    }
}

이를 통해 애플리케이션의 현재 상태를 반영하는 생성된 OpenAPI 문서를 /openapi 경로에서 액세스할 수 있습니다.

OpenAPI 컴파일러 확장 및 런타임 API에 대한 자세한 내용은 OpenAPI 사양 생성을 참조하세요.

OpenAPI 구성

기본적으로 문서는 StaticHtml2Codegen을 사용하여 렌더링됩니다. openAPI {} 블록 내에서 렌더러를 커스터마이징할 수 있습니다.

routing {
    openAPI(path="openapi", swaggerFile = "openapi/documentation.yaml") {
        codegen = StaticHtmlCodegen()
    }
}