OpenAPI
필수 의존성: io.ktor:ktor-server-openapi
코드 예제: json-kotlinx-openapi
네이티브 서버Ktor는 Kotlin/Native를 지원하므로 추가 런타임이나 가상 머신 없이도 서버를 실행할 수 있습니다. 지원: ✖️
Ktor를 사용하면 OpenAPI 명세를 기반으로 OpenAPI 문서를 제공(serve)할 수 있습니다.
다음 방법 중 하나로 OpenAPI 명세를 제공할 수 있습니다:
두 경우 모두 OpenAPI 플러그인이 서버에서 명세를 조합하고 문서를 HTML로 렌더링합니다.
의존성 추가
OpenAPI 문서를 제공하려면 빌드 스크립트에
ktor-server-openapi아티팩트를 추가해야 합니다:kotlinimplementation(ktorLibs.server.openapi)위의 코드 스니펫은 Ktor 버전 카탈로그를 사용하여 Ktor 의존성을 지정합니다.groovyimplementation 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의존성을 추가합니다:kotlinimplementation("io.swagger.codegen.v3:swagger-codegen-generators:$swagger_codegen_version")groovyimplementation "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를 렌더링합니다:
import io.ktor.server.plugins.openapi.*
// ...
routing {
openAPI(path="openapi", swaggerFile = "openapi/documentation.yaml")
}플러그인은 먼저 애플리케이션 리소스에서 명세를 찾습니다. 찾지 못한 경우 java.io.File을 사용하여 파일 시스템에서 로드하려고 시도합니다.
런타임 OpenAPI 메타데이터 생성
정적 파일에 의존하는 대신, OpenAPI 컴파일러 플러그인과 라우트 애너테이션에 의해 생성된 메타데이터를 사용하여 런타임에 OpenAPI 명세를 생성할 수 있습니다.
이 모드에서는 OpenAPI 플러그인이 라우팅 트리에서 직접 명세를 조합합니다:
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()를 사용하여 태그와 설명을 정의할 수 있습니다:
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 프로퍼티에 할당하세요:
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으로 유지하세요.
