User Guide

This guide walks you through installing the tapik Gradle plugin, declaring endpoints with the Kotlin DSL, and running the generators that create clients, servers, and documentation.

Tip

New to tapik? Start with Getting Started for a step-by-step tutorial before diving into the full plugin reference below.

Prerequisites

• JDK compatible with the repository defaults (javaTargetVersion=21, toolchain javaToolchainVersion=24 in gradle.properties).
• Gradle 9+ with the Kotlin DSL; configuration cache and task caching are supported out of the box.
• Kotlin 2.2.20 (supplied via the GRADLE toolchain).
• Optional modules you plan to use, such as dev.akif.tapik:jackson for JSON bodies or Spring starters for generated code.

Component	Example Dependency
Endpoint DSL	implementation("dev.akif.tapik:core:0.1.2")
Codecs	implementation("dev.akif.tapik:codec:0.1.2")
Jackson integration	implementation("dev.akif.tapik:jackson:0.1.2")
Gradle plugin	id("dev.akif.tapik.plugin.gradle") version "0.1.2"

Note

The version numbers match the repository snapshot (version=0.1.2). Replace them with the release you are consuming.

Installing the Gradle Plugin

Configure the plugin in a module that produces HTTP endpoints or needs generated sources:

plugins {
    kotlin("jvm")
    id("dev.akif.tapik.plugin.gradle") version "0.1.2"
}

dependencies {
    implementation("dev.akif.tapik:core:0.1.2")
    implementation("dev.akif.tapik:jackson:0.1.2") // for JSON helpers
}

tapik {
    endpointPackages(
        "com.acme.catalog.endpoints",
        "com.acme.shared.http"
    )

    springRestClient { /* enables the Spring RestClient generator */ }
    springWebMvc { /* enables the Spring WebMVC generator */ }
    markdownDocumentation { /* enables the Markdown documentation generator */ }
}

Key things to remember:

• endpointPackages must reference the packages where compiled endpoint properties live. The scanner filters classes using these prefixes.
• The nested generator blocks are markers; you do not need to configure anything inside them unless future versions expose options.
• Generated Kotlin sources land under build/generated/sources/tapik/main/kotlin and are added to the main source set automatically.
• Non-source artefacts (for example, Markdown files) are written under build/generated.

Declaring Endpoints

Endpoints are compile-time constants built with the DSL in the core module. The DSL collects metadata from property names, documentation strings, and nested builders.

package com.acme.catalog.endpoints

import dev.akif.tapik.*
import dev.akif.tapik.jackson.jsonBody

object ProductEndpoints {
    private val productId = path.uuid("productId")
    private val locale = query.string("locale").optional("en-US")

    val getProduct by http(
        description = "Fetch product details",
        details = "Returns localized information when the locale query parameter is supplied."
    ) {
        get.uri(root / "products" / productId + locale)
            .input(header.uuid("X-Request-Id"))
            .output(Status.OK) {
                jsonBody<ProductView>("product")
            }
            .output(Status.NOT_FOUND) {
                jsonBody<ProblemDetails>("problem")
            }
    }
}

Highlights:

• http { ... } infers the endpoint id from the property name (getProduct). The description and details flow into generated KDoc and Markdown.
• Path building uses operator overloads: root / "products" / productId.
• Query parameters append with +, headers with input { ... }, and outputs use output(Status.OK) { ... }.
• Response variants can be chained; the DSL supports OneOf unions to model branching behaviour.

Running Generation

tapik registers an aggregated tapikGenerate task. It depends on classes for the current project and its siblings to ensure bytecode is available.

./gradlew :service:tapikGenerate

Execution flow:

1. Compiled classes are scanned for properties that return HttpEndpoint.
2. Metadata describing the endpoints is persisted to build/generated/tapik-endpoints.txt.
3. The selected generators (spring-restclient, spring-webmvc, markdown-docs) run sequentially.
4. Generated sources are attached to the IDE/classpath; you can ./gradlew build without special configuration.

Tip

You can run ./gradlew :service:classes tapikGenerate during fast feedback loops. Pass -PskipLint if you want to avoid ktlint locally.

Inspecting Outputs

• Kotlin sources live under build/generated/sources/tapik/main/kotlin.
• Markdown documentation is emitted to build/generated/API.md.
• Scan report: build/generated/tapik-endpoints.txt contains the raw metadata list.

When checking generated Kotlin into source control:

• Run ./gradlew tapikGenerate after any endpoint changes.
• Review generated types as you would review hand-written code; they carry KDoc extracted from your endpoints.
• For reproducibility, make sure the versions of tapik dependencies are pinned via a version catalog or BOM.

Troubleshooting

Symptom	Common Cause	Fix
Missing compiled classes warning	classes task did not run before tapikGenerate	Run ./gradlew classes tapikGenerate or wire tasks in your CI pipeline
No generators execute	Generator blocks omitted in the tapik extension	Add springRestClient { }, springWebMvc { }, or markdownDocumentation { }
Class not found during scan	Endpoint package not covered by endpointPackages	Ensure fully qualified package prefixes are listed
Unexpected HTTP mappings	Endpoint root path missing leading segment	Start URIs with root / "segment" or "segment" / ...

If you create custom generators, place their implementation on the build classpath and expose them via the Java ServiceLoader contract. The Gradle plugin will pick them up automatically when their id is enabled.