Skip to content
Server Plugin

OpenAPI

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

코드 예제: json-kotlinx-openapi

네이티브 서버Ktor는 Kotlin/Native를 지원하므로 추가 런타임이나 가상 머신 없이도 서버를 실행할 수 있습니다. 지원: ✖️

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

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

두 경우 모두 OpenAPI 플러그인이 서버에서 명세를 조합하고 문서를 HTML로 렌더링합니다.

의존성 추가 ​

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

    kotlin
    implementation(ktorLibs.server.openapi)
    위의 코드 스니펫은 Ktor 버전 카탈로그를 사용하여 Ktor 의존성을 지정합니다.
    groovy
    implementation ktorLibs.server.openapi
    위의 코드 스니펫은 Ktor 버전 카탈로그를 사용하여 Ktor 의존성을 지정합니다.
    xml
    <dependency>
        <groupId>io.ktor</groupId>
        <artifactId>ktor-server-openapi-jvm</artifactId>
        <version>${ktor_version}</version>
    </dependency>
  • 코드 생성기(code generator)를 커스터마이즈하려는 경우, 선택적으로 swagger-codegen-generators 의존성을 추가합니다:

    kotlin
    implementation("io.swagger.codegen.v3:swagger-codegen-generators:$swagger_codegen_version")
    groovy
    implementation "io.swagger.codegen.v3:swagger-codegen-generators:$swagger_codegen_version"
    xml
    <dependency>
        <groupId>io.swagger.codegen.v3</groupId>
        <artifactId>swagger-codegen-generators</artifactId>
        <version>${swagger_codegen_version}</version>
    </dependency>

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

정적 OpenAPI 파일 사용 ​

기존 명세로부터 OpenAPI 문서를 제공하려면 OpenAPI 문서 경로를 지정하여 openAPI() 함수를 사용합니다.

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

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

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

플러그인은 먼저 애플리케이션 리소스에서 명세를 찾습니다. 찾지 못한 경우 java.io.File을 사용하여 파일 시스템에서 로드하려고 시도합니다.

런타임 OpenAPI 메타데이터 생성 ​

정적 파일에 의존하는 대신, OpenAPI 컴파일러 플러그인과 라우트 애너테이션에 의해 생성된 메타데이터를 사용하여 런타임에 OpenAPI 명세를 생성할 수 있습니다.

이 모드에서는 OpenAPI 플러그인이 라우팅 트리에서 직접 명세를 조합합니다:

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

이렇게 하면 /openapi 경로에서 애플리케이션의 현재 상태를 반영하는 생성된 OpenAPI 문서에 접근할 수 있습니다.

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

OpenAPI 구성 ​

openAPI {} 구성 블록을 사용하면 생성된 OpenAPI 문서와 Ktor가 문서를 렌더링하는 방식을 구성할 수 있습니다.

문서 메타데이터 구성 ​

구성 블록에서 최상위 레벨의 OpenAPI 메타데이터를 직접 정의할 수 있습니다.

예를 들어, info를 사용하여 일반적인 API 정보를 지정하고 tag()를 사용하여 태그와 설명을 정의할 수 있습니다:

kotlin
openAPI("openapi") {
    info = OpenApiInfo("Books API from routes", "1.0.0")
    tag(
        name = "Books",
        description = "Operations on books"
    )
}

서버, 보안 요구사항, 재사용 가능한 컴포넌트, 외부 문서, 명세 확장(specification extension)과 같은 기타 최상위 OpenAPI 프로퍼티도 구성할 수 있습니다.

사용 가능한 전체 옵션 목록은 OpenAPIConfig API 레퍼런스를 참조하세요.

문서 렌더러 구성 ​

기본적으로 문서는 StaticHtml2Codegen을 사용하여 렌더링됩니다.

다른 렌더러를 사용하려면 codegen 프로퍼티에 할당하세요:

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

StaticHtmlCodegen 및 StaticHtml2Codegen은 OpenAPI 3.0.x 문서만 지원합니다. OpenAPI 3.1 문서와 함께 사용하면 불완전하거나 올바르지 않은 HTML이 생성될 수 있습니다. OpenAPI 3.1의 경우 Swagger UI 5.x와 함께 swaggerUI() 함수를 사용하세요. OpenAPI 플러그인의 HTML 렌더러를 계속 사용해야 한다면 명세를 OpenAPI 3.0.3으로 유지하세요.