justworks

A Gradle plugin that generates type-safe Kotlin Ktor client code from OpenAPI 3.0 specifications.

Installation

Add the plugin to your build.gradle.kts:

plugins {
    id("com.avsystem.justworks") version "<version>"
}

The plugin and core library are published to Maven Central:

• com.avsystem.justworks:plugin -- Gradle plugin
• com.avsystem.justworks:core -- OpenAPI parser and code generator

Usage

Configure one or more OpenAPI specs in the justworks extension:

justworks {
    specs {
        register("petstore") {
            specFile = file("api/petstore.yaml")
            packageName = "com.example.petstore"
        }
        register("payments") {
            specFile = file("api/payments.yaml")
            packageName = "com.example.payments"
            // Optional: override default sub-packages
            apiPackage = "com.example.payments.client"
            modelPackage = "com.example.payments.dto"
        }
    }
}

Each spec gets its own Gradle task (justworksGenerate<Name>) and output directory. Run all generators at once with:

./gradlew justworksGenerateAll

Generated sources are automatically wired into Kotlin source sets, so compileKotlin depends on code generation -- no extra configuration needed.

Configuration options

Property	Required	Default	Description
specFile	Yes	--	Path to the OpenAPI spec (.yaml/.json)
packageName	Yes	--	Base package for generated code
apiPackage	No	$packageName.api	Package for API client classes
modelPackage	No	$packageName.model	Package for model/data classes

Publishing

Releases are published to Maven Central automatically when a version tag (v*) is pushed. The CD pipeline runs CI checks first, then publishes signed artifacts via the vanniktech maven-publish plugin.

To trigger a release:

git tag v1.0.0
git push origin v1.0.0

The version is derived from the tag (stripping the v prefix). Without a tag, the version defaults to 0.0.1-SNAPSHOT.

Development

Requires JDK 21+.

# Run tests and linting
./gradlew check

# Run only unit tests
./gradlew test

# Run functional tests (plugin module)
./gradlew plugin:functionalTest

# Lint check
./gradlew ktlintCheck

License

Apache License 2.0