or run

tessl search

tessl/maven-io-quarkus--quarkus-resteasy-reactive

tessl install tessl/maven-io-quarkus--quarkus-resteasy-reactive@3.15.0

A Jakarta REST implementation utilizing build time processing and Vert.x for high-performance REST endpoints with reactive capabilities in cloud-native environments.

Kotlin Serialization

Quarkus REST provides full support for Kotlin Serialization as an alternative to Jackson or JSON-B for JSON processing. It allows Kotlin applications to use kotlinx.serialization for type-safe serialization and deserialization with extensive configuration options.

Import

import io.quarkus.resteasy.reactive.kotlin.serialization.common.JsonBuilderCustomizer
import io.quarkus.resteasy.reactive.kotlin.serialization.common.runtime.KotlinSerializationConfig
import io.quarkus.resteasy.reactive.kotlin.serialization.common.runtime.JsonConfig
import kotlinx.serialization.*
import kotlinx.serialization.json.*

Capabilities

JsonBuilderCustomizer

CDI bean interface for customizing the JSON serialization builder at application startup.

/**
 * Interface for customizing JsonBuilder configuration
 * Implement as a CDI bean to customize JSON serialization settings
 */
interface JsonBuilderCustomizer {
    /**
     * Customize the JsonBuilder
     * @param jsonBuilder The JsonBuilder to customize
     */
    fun customize(jsonBuilder: JsonBuilder)

    /**
     * Priority for ordering multiple customizers (lower values execute first)
     * @return Priority value (default: 0)
     */
    fun priority(): Int = DEFAULT_PRIORITY

    /**
     * Compare priority with another customizer
     * @param o Other customizer to compare with
     * @return Comparison result
     */
    fun compareTo(o: JsonBuilderCustomizer): Int = Integer.compare(priority(), o.priority())

    companion object {
        const val DEFAULT_PRIORITY = 0
    }
}

KotlinSerializationConfig

Build-time and runtime configuration for Kotlin Serialization.

/**
 * Configuration root for Kotlin Serialization
 * Configured via quarkus.kotlin-serialization.* properties
 */
class KotlinSerializationConfig {
    /**
     * JSON-specific configuration
     */
    val json: JsonConfig
}

JsonConfig

Detailed JSON serialization configuration with 15+ properties controlling serialization behavior.

/**
 * JSON serialization configuration
 * Configured via quarkus.kotlin-serialization.json.* properties
 */
class JsonConfig {
    /**
     * Allow special floating-point values (NaN, Infinity, -Infinity)
     * Default: false
     */
    val allowSpecialFloatingPointValues: Boolean = false

    /**
     * Allow structured (non-primitive) map keys
     * Default: false
     */
    val allowStructuredMapKeys: Boolean = false

    /**
     * Property name for polymorphic type discriminator
     * Default: "type"
     */
    val classDiscriminator: String = "type"

    /**
     * Coerce incorrect JSON values to default values instead of failing
     * Default: false
     */
    val coerceInputValues: Boolean = false

    /**
     * Encode default values even if they match the property default
     * Default: true
     */
    val encodeDefaults: Boolean = true

    /**
     * Encode null values explicitly in JSON output
     * Default: true
     */
    val explicitNulls: Boolean = true

    /**
     * Ignore unknown keys in JSON input instead of failing
     * Default: false
     */
    val ignoreUnknownKeys: Boolean = false

    /**
     * Enable lenient parsing mode (relaxed JSON parsing)
     * Default: false
     */
    val isLenient: Boolean = false

    /**
     * Pretty print JSON output with indentation
     * Default: false
     */
    val prettyPrint: Boolean = false

    /**
     * Indentation string for pretty printing
     * Default: "    " (4 spaces)
     */
    val prettyPrintIndent: String = "    "

    /**
     * Use alternative names from @JsonNames annotation
     * Default: true
     */
    val useAlternativeNames: Boolean = true

    /**
     * Use array format for polymorphic serialization instead of object format
     * Default: false
     */
    val useArrayPolymorphism: Boolean = false

    /**
     * JSON naming strategy for property names
     * Optional: Can be a fully qualified class name implementing NamingStrategy
     */
    val namingStrategy: String? = null

    /**
     * Decode enum values case-insensitively
     * Default: false
     */
    val decodeEnumsCaseInsensitive: Boolean = false

    /**
     * Allow trailing commas in JSON objects and arrays
     * Default: false
     */
    val allowTrailingComma: Boolean = false

    /**
     * Allow C-style (/* */) and Java-style (//) comments in JSON
     * Default: false
     */
    val allowComments: Boolean = false
}

Configuration

Configure Kotlin Serialization via application.properties:

# Special floating-point values
quarkus.kotlin-serialization.json.allow-special-floating-point-values=false

# Structured map keys
quarkus.kotlin-serialization.json.allow-structured-map-keys=false

# Polymorphic type discriminator
quarkus.kotlin-serialization.json.class-discriminator=type

# Coerce incorrect values
quarkus.kotlin-serialization.json.coerce-input-values=false

# Encode defaults
quarkus.kotlin-serialization.json.encode-defaults=true

# Explicit nulls
quarkus.kotlin-serialization.json.explicit-nulls=true

# Ignore unknown keys
quarkus.kotlin-serialization.json.ignore-unknown-keys=false

# Lenient parsing
quarkus.kotlin-serialization.json.is-lenient=false

# Pretty print
quarkus.kotlin-serialization.json.pretty-print=false
quarkus.kotlin-serialization.json.pretty-print-indent=

# Alternative names
quarkus.kotlin-serialization.json.use-alternative-names=true

# Array polymorphism
quarkus.kotlin-serialization.json.use-array-polymorphism=false

# Naming strategy
quarkus.kotlin-serialization.json.naming-strategy=com.example.MyNamingStrategy

# Case-insensitive enums
quarkus.kotlin-serialization.json.decode-enums-case-insensitive=false

# Trailing commas
quarkus.kotlin-serialization.json.allow-trailing-comma=false

# Comments in JSON
quarkus.kotlin-serialization.json.allow-comments=false

Usage Examples

Basic Kotlin REST Endpoint

import jakarta.ws.rs.*
import kotlinx.serialization.Serializable

@Serializable
data class User(
    val id: String,
    val name: String,
    val email: String
)

@Path("/users")
class UserResource {

    @GET
    @Path("/{id}")
    fun getUser(@PathParam("id") id: String): User {
        return User(id, "John Doe", "john@example.com")
    }

    @POST
    fun createUser(user: User): User {
        return user
    }
}

Custom JsonBuilder Configuration

import io.quarkus.resteasy.reactive.kotlin.serialization.common.JsonBuilderCustomizer
import jakarta.enterprise.context.ApplicationScoped
import kotlinx.serialization.json.JsonBuilder

@ApplicationScoped
class CustomJsonConfig : JsonBuilderCustomizer {

    override fun customize(jsonBuilder: JsonBuilder) {
        jsonBuilder.apply {
            prettyPrint = true
            ignoreUnknownKeys = true
            coerceInputValues = true
            encodeDefaults = false
        }
    }

    override fun priority(): Int = 100
}

Multiple Customizers with Priority

@ApplicationScoped
class HighPriorityCustomizer : JsonBuilderCustomizer {

    override fun customize(jsonBuilder: JsonBuilder) {
        jsonBuilder.isLenient = true
    }

    override fun priority(): Int = 10
}

@ApplicationScoped
class LowPriorityCustomizer : JsonBuilderCustomizer {

    override fun customize(jsonBuilder: JsonBuilder) {
        jsonBuilder.prettyPrint = true
    }

    override fun priority(): Int = 100
}

Polymorphic Serialization

@Serializable
sealed class Animal {
    abstract val name: String
}

@Serializable
@SerialName("dog")
data class Dog(override val name: String, val breed: String) : Animal()

@Serializable
@SerialName("cat")
data class Cat(override val name: String, val lives: Int = 9) : Animal()

@Path("/animals")
class AnimalResource {

    @GET
    fun getAnimals(): List<Animal> {
        return listOf(
            Dog("Buddy", "Golden Retriever"),
            Cat("Whiskers", 9)
        )
    }
}

With configuration:

# Use custom discriminator name
quarkus.kotlin-serialization.json.class-discriminator=@type

# Result JSON:
# [
#   {"@type":"dog","name":"Buddy","breed":"Golden Retriever"},
#   {"@type":"cat","name":"Whiskers","lives":9}
# ]

Handling Unknown Keys

@Serializable
data class PartialUser(
    val id: String,
    val name: String
    // email field is not defined
)

@Path("/api")
class ApiResource {

    @POST
    @Path("/partial")
    fun processPartial(user: PartialUser): PartialUser {
        // With ignore-unknown-keys=true, extra fields are silently ignored
        return user
    }
}

Configuration:

# Allow JSON with extra fields
quarkus.kotlin-serialization.json.ignore-unknown-keys=true

# POST with: {"id":"123","name":"John","email":"john@example.com"}
# Will successfully deserialize, ignoring "email" field

Lenient Parsing

@Path("/lenient")
class LenientResource {

    @POST
    fun parseRelaxed(data: Map<String, String>): Map<String, String> {
        return data
    }
}

Configuration:

# Enable lenient mode for relaxed JSON parsing
quarkus.kotlin-serialization.json.is-lenient=true

# Accepts: {key: 'value', 'another': "value2"}
# (unquoted keys, single quotes, etc.)

Pretty Printing for Development

# Development configuration
%dev.quarkus.kotlin-serialization.json.pretty-print=true
%dev.quarkus.kotlin-serialization.json.pretty-print-indent=

# Production configuration (compact)
%prod.quarkus.kotlin-serialization.json.pretty-print=false

Case-Insensitive Enums

@Serializable
enum class Status {
    ACTIVE,
    INACTIVE,
    PENDING
}

@Serializable
data class Order(
    val id: String,
    val status: Status
)

@Path("/orders")
class OrderResource {

    @POST
    fun createOrder(order: Order): Order {
        return order
    }
}

Configuration:

# Allow case-insensitive enum values
quarkus.kotlin-serialization.json.decode-enums-case-insensitive=true

# Accepts: {"id":"123","status":"active"}
# Accepts: {"id":"123","status":"ACTIVE"}
# Accepts: {"id":"123","status":"Active"}

Allowing Special Float Values

@Serializable
data class MathResult(
    val value: Double,
    val isValid: Boolean
)

@Path("/math")
class MathResource {

    @GET
    @Path("/divide/{a}/{b}")
    fun divide(
        @PathParam("a") a: Double,
        @PathParam("b") b: Double
    ): MathResult {
        val result = a / b
        return MathResult(result, result.isFinite())
    }
}

Configuration:

# Allow NaN and Infinity values in JSON
quarkus.kotlin-serialization.json.allow-special-floating-point-values=true

# Result: {"value":Infinity,"isValid":false}

Best Practices

Development vs Production Settings

# Development: verbose and forgiving
%dev.quarkus.kotlin-serialization.json.pretty-print=true
%dev.quarkus.kotlin-serialization.json.is-lenient=true
%dev.quarkus.kotlin-serialization.json.ignore-unknown-keys=true

# Production: strict and compact
%prod.quarkus.kotlin-serialization.json.pretty-print=false
%prod.quarkus.kotlin-serialization.json.is-lenient=false
%prod.quarkus.kotlin-serialization.json.ignore-unknown-keys=false

API Versioning

# For backward compatibility, ignore unknown keys
quarkus.kotlin-serialization.json.ignore-unknown-keys=true

# For forward compatibility, encode defaults
quarkus.kotlin-serialization.json.encode-defaults=true

Public APIs

# Strict validation for public APIs
quarkus.kotlin-serialization.json.coerce-input-values=false
quarkus.kotlin-serialization.json.ignore-unknown-keys=false
quarkus.kotlin-serialization.json.is-lenient=false

Internal APIs

# More permissive for internal microservices
quarkus.kotlin-serialization.json.ignore-unknown-keys=true
quarkus.kotlin-serialization.json.decode-enums-case-insensitive=true

Integration with REST Client

Kotlin Serialization works seamlessly with REST Client:

@Path("/api")
@RegisterRestClient(configKey = "external-api")
interface ExternalApiClient {

    @GET
    @Path("/data")
    suspend fun getData(): KotlinSerializedData

    @POST
    @Path("/data")
    suspend fun postData(data: KotlinSerializedData): Response
}

The same Kotlin Serialization configuration applies to both server and client side.