Documentation

With genhttp-kt, developers can quickly create new web services on the JVM. Everything else is provided by the server infrastructure as well as the ecosystem of Kotlin and the JVM, which easily allows to build, test and run applications.

Similar to frameworks like Javalin or http4k, and in comparison to Spring Boot, genhttp-kt emphasizes a gentle learning curve to enable fast results. You should be able to set up a new web service or website in a couple of minutes.

Getting Started

genhttp-kt requires JDK 25 or newer and is built with Kotlin 2.4. To host a server in an existing or new project, add a dependency on genhttp-full from Maven Central:

dependencies {
    implementation("org.genhttp:genhttp-full:11.1.0.3")
}

<dependency>
    <groupId>org.genhttp</groupId>
    <artifactId>genhttp-full</artifactId>
    <version>11.1.0.3</version>
</dependency>

Then spin off a new host:

import org.genhttp.engine.internal.Host

import org.genhttp.modules.apibrowsing.*
import org.genhttp.modules.functional.*
import org.genhttp.modules.layouting.*
import org.genhttp.modules.openapi.*
import org.genhttp.modules.practices.*

suspend fun main() {
    // use a handler of your choice (see the samples below)
    val api = Layout.create()
        .add(Inline.create().get { "Hello World" })
        .addOpenApi()
        .addScalar()

    Host.create()
        .handler(api)
        .defaults()
        .run() // or .start() to return immediately and keep the application running
}

Running this snippet will provide the following endpoints:

genhttp-full contains the engine and every module. If you only need the engine and the basic modules (IO, layouting and best practices), depend on genhttp-core instead and add the modules you use individually - every page of this documentation names the package of its module. genhttp-full-netty and genhttp-core-netty are the same on the Netty engine, which serves your application from Netty event loops.

Samples

The playground project provides a quick starting point to view sample code - layouts, webservices, functional handlers, controllers, static files and single page applications. Clone the repository and run it with ./gradlew :playground:run.

Next Steps

The example project above gives you a basic idea of how projects developed with genhttp-kt might look like. To create more complex web applications, follow the guides in the following sections: