annotations/io.github.kingg22.ktorgen.core/KtorGen

KtorGen

@Target(allowedTargets = [AnnotationTarget.CLASS])

annotation class KtorGen(val name: String = KTORGEN_DEFAULT_NAME, val generate: Boolean = true, @Language(value = "http-url-reference") val basePath: String = "", val generateTopLevelFunction: Boolean = true, val generateCompanionExtFunction: Boolean = false, val generateHttpClientExtension: Boolean = false, val propagateAnnotations: Boolean = true, val annotations: Array<KClass<out Annotation>> = [], val optInAnnotations: Array<KClass<out Annotation>> = [], val functionAnnotations: Array<KClass<out Annotation>> = [], val visibilityModifier: String = KTORGEN_DEFAULT_NAME, val classVisibilityModifier: String = KTORGEN_DEFAULT_NAME, val constructorVisibilityModifier: String = KTORGEN_DEFAULT_NAME, val functionVisibilityModifier: String = KTORGEN_DEFAULT_NAME, val customFileHeader: String = KTORGEN_DEFAULT_NAME, val customClassHeader: String = "")

Indicates that an interface should be used for Ktor Client code generation.

This annotation controls how the generated class and companion/helper functions are emitted. It is expected to be used on the interface itself or optionally on its companion object for factory generation.

Basic usage:

interface UserRoute {
    // Interface definition
    // empty definition don't generate code*

    @KtorGen
    companion object
}

val route: UserRoute

route = _UserRouteImpl(httpClient) // Constructor of impl class
route = UserRoute(httpClient) // Factory top-level function (if enabled)
route = UserRoute.create(httpClient) // Companion factory (if enabled and Companion is available)
route = httpClient.userRoute() // Extension function of HttpClient (if enabled)

The generated implementation will:

Be named with an optional prefix or custom name.
Implement the target interface with the same visibility modifier.
Receive an HttpClient as its primary constructor argument.
Propagate annotations.
Mark all generated code with @Generated and add comments.
Declare a factory top level function.

Properties

annotations

@KtorGenExperimental

val annotations: Array<KClass<out Annotation>>

KtorGenExperimental Additional annotations or only these annotations to propagate as-is from the interface to the generated implementation class and extension functions, see more info about functions.

basePath

val basePath: String

Set a base path (or URL) for the current interface, all generated functions going to init with this + it path.

classVisibilityModifier

@KtorGenExperimental

val classVisibilityModifier: String

KtorGenExperimental Control the visibility modifier of the generated class only.

constructorVisibilityModifier

@KtorGenExperimental

val constructorVisibilityModifier: String

KtorGenExperimental Control the visibility modifier of the generated primary constructor only.

customClassHeader

val customClassHeader: String

Custom KDoc comment or annotations for the generated implementation class.

customFileHeader

val customFileHeader: String

Custom header comment inserted at the top of the generated Kotlin file.

functionAnnotations

@KtorGenExperimental

val functionAnnotations: Array<KClass<out Annotation>>

KtorGenExperimental Additional annotations or only these annotations to propagate as-is to the generated extension functions:

functionVisibilityModifier

@KtorGenExperimental

val functionVisibilityModifier: String

KtorGenExperimental Control the visibility modifier of the generated extension functions only.

generate

val generate: Boolean = true

Indicate the annotated interface going to generate the code or not.

generateCompanionExtFunction

val generateCompanionExtFunction: Boolean = false

Whether to generate a create(client) extension function of interface's companion object.

generateHttpClientExtension

val generateHttpClientExtension: Boolean = false

Whether to generate an extension function on HttpClient to instantiate the API.

generateTopLevelFunction

val generateTopLevelFunction: Boolean = true

Whether to generate a top-level function in the same package as the interface.

name

val name: String

Custom name for the generated implementation class.

optInAnnotations

@KtorGenExperimental

val optInAnnotations: Array<KClass<out Annotation>>

KtorGenExperimental Opt-in annotations that should be propagated to generated class and extension functions, need be marked with @RequiresOptIn or @SubclassOptInRequired, otherwise the generated code will not compile because requirements of @OptIn.

propagateAnnotations

@KtorGenExperimental

val propagateAnnotations: Boolean = true

KtorGenExperimental Indicate if annotations from the source interface should be copied to the generated class and extension functions.

visibilityModifier

@KtorGenExperimental

val visibilityModifier: String

KtorGenExperimental Indicate the visibility modifier for all generated code (class, primary constructor, and extension functions)

KtorGen

See also

Properties