ktor-docs

⚠️ Deprecation notice ⚠️

This project is now superseded by the official way of generating OpenAPI docs

Usage

Add dependencies

Latest stable build

Latest snapshot build

build.gradle.kts

repositories {
    maven("https://repo.h4kt.dev/releases")
}

dependencies {
    implementation("dev.h4kt:ktor-docs:<latest-version>")
}

Plugin installation

fun Application.module() {

    install(KtorDocs) {
    
        openApi {

            version = "3"
    
            info {
                version = "1"
                title = "Template project docs"
            }
    
            server {
                url = "http://localhost:1337"
                description = "Local development server"
            }

        }

        swagger {
            path = "/docs"
        }
        
    }
    
}

Usage

In order for your route to be included in the resulting specification it has to be defined using a custom extension function provided by KtorDocs

GreetingController.kt

import dev.h4kt.ktorDocs.dsl.get

fun Routing.configureEchoRouting() = route("/greet") {

    class EchoParams : RouteParameters() {
        val name by query.string {
            name = "name"
            description = "Name of whoever to greet"
        }
    }

    get(::EchoParams) {

        description = "An API endpoint to greet whoever hits it"

        responses {
            HttpStatusCode.OK returns typeInfo<String>()
        }

        handle {
            call.respond("Greetings, ${parameters.name}")
        }

    }

}

Custom type converters

KtorDocs supports all primitive types, kotlin.time.Duration, kotlin.time.Instant, kotlinx.datetime.*, kotlin.uuid.Uuid, java.util.UUID, collections and data class types out of the box

To handle other types you can implement a custom converter:

class KotlinUuidTypeConverter : TypeConverter(priority = 900) {

    override fun canConvert(type: KType): Boolean {
        return type.classifierKClass == Uuid::class
    }

    override fun convert(
        type: KType,
        parentTypes: Collection<KType>,
        classifier: KClass<*>,
        convertDownstream: (type: KType) -> OpenApiSchema
    ): OpenApiSchema {
        return OpenApiSchema.String(
            format = "UUID",
            nullable = type.isMarkedNullable
        )
    }

}

// Plugin setup
fun Application.module() {
    install(KtorDocs) {
        // ...
        typeConverters(KotlinUuidTypeConverter())
    }
}

Custom authentication provider converters

KtorDocs supports Basic, Bearer and OAuth providers out of the box

To handle other types of authentication providers you can implement a custom converter:

class BasicAuthProviderConverter : AuthProviderConverter(priority = 100) {

    override fun canConvert(
        provider: AuthenticationProvider
    ): Boolean {
        return provider is BasicAuthenticationProvider
    }

    override fun convert(
        provider: AuthenticationProvider,
        application: Application
    ): OpenApiSecurityScheme {
        require(provider is BasicAuthenticationProvider)
        return OpenApiSecurityScheme.Http(scheme = BASIC)
    }

}

// Plugin setup
fun Application.module() {
    install(KtorDocs) {
        // ...
        authProviderConverters(BasicAuthProviderConverter())
    }
}