Skip to content

Vladiatro/ktor-query-params

Repository files navigation

Ktor Query Params Library

The ktor-query-params library consists of two modules that provide defined handling of query parameters and automatic generation of Swagger definitions for Ktor endpoints.

Modules

ktor-query-params

The ktor-query-params module introduces a convenient way to define and manage query parameters and responses in Ktor applications. It enables you to pre-declare query parameters with explicit type checks and conversions, ensuring that your code adheres to the specified contract.

Installing (Gradle)

implementation("net.falsetrue:ktor-query-params:0.2.0")

Features

  • Declare query parameters and responses in advance.
  • Ensure type correctness and automatic conversions.
  • Extensions to access parameters in an easier way within a call (param.get(), response.send())

Usage Example

routing {
    route("/test") {
        val stringParam = stringParam("string") // String?
        val intParam = intParam("int") // Int?
        val boolParam = boolParam("bool") // Bool?
        val requiredParam = stringParam("required")
            .required() // String
        val manyParam = stringParam("manyParam").many() // List<String>
        val enumParam = enumParam<TestEnum>("enum") // TestEnum?
        val localDateParam = localDateParam("localDate") // LocalDate?
            .onParseError { paramName, parsedString ->
                throw IllegalArgumentException("Wrong $paramName: $parsedString")
            }
        val requiredParamIfBoolIsTrue = stringParam("requiredIfBoolIsTrue")
            .convert {
                if (boolParam.get() && it == null) {
                    throw IllegalArgumentException("$paramName should be specified if bool is true")
                }
                it
            }

        val okResult = responds<Result>()
        
        // Custom extensions to simplify handling
        doGet {
            okResult.send(
                Result(
                    stringParam.get(),
                    intParam.get(),
                    boolParam.get(),
                    requiredParam.get(),
                    manyParam.get(),
                    enumParam.get(),
                    localDateParam.get(),
                    requiredParamIfBoolIsTrue.get()
                )
            )
        }
        
        // Ktor native alternative
        post {
            call.send(okResult, Result(
                call.get(stringParam),
                // ...
            ))
        }
    }
}

ktor-query-params-openapi-generator

The ktor-query-params-openapi-generator module wraps the io.swagger:swagger-core library and facilitates the automatic generation of Swagger definitions for Ktor endpoints that utilize query parameters defined with the prior module.

Installing (Gradle)

implementation("net.falsetrue:ktor-query-params-openapi-generator:0.2.0")

Features

  • Generate Swagger definitions for Ktor endpoints with query parameters.
  • Keep API documentation aligned with query parameter declarations.

Usage Example

install(KtorOpenapiPlugin) {
    swagger.info = Info().apply {
        version = "1.0.0"
        title = "Test API"
    }
}

routing {
    route("/test") {
        val stringParam = stringParam("string")
            .description("A string param")
        val hiddenParam = stringParam("hiddenString")
            .hidden()
        val customSwaggerProperty = stringParam("email")
            .openApi(EmailProperty())

        val okResult = responds<Result>()

        openApi {
            get.tags = listOf("tag1", "tag2")
        }
        doGet {
            okResult.send(
                Result(
                    stringParam.get(),
                    hiddenParam.get(),
                    customSwaggerProperty.get()
                )
            )
        }
    }
    route("/exlude") {
        excludeFromApi()
        get { /* ... */ }
    }
    // the definition will be accessible via a GET request to swagger.json
    swaggerJsonRoute()
}

The definition will be available under /swagger.json endpoint (customizable in swaggerJsonRoute). It will contain query params and results defined with the ktor-query-params library. Request bodies are not currently supported (you can use io.ktor:ktor-server-swagger-jvm generator for them).

Contributions

Contributions to the ktor-query-params library are welcome! If you find any issues or have suggestions for improvements, please open an issue or submit a pull request on the GitHub repository.

License

This project is licensed under the Apache License 2.0.

About

Ktor Query Params

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages