Plugin Options¶

These options control the plugin's behavior, including output format, file location, and build performance.

Basic Options¶

swagger {
    pluginOptions {
        enabled = true
        saveInBuild = true
        format = "yaml"
        filePath = null
        regenerationMode = "strict"
    }
}

Option Reference¶

enabled¶

Enables or disables the plugin entirely.

enabled = true // default

Set to false to temporarily disable OpenAPI generation without removing the plugin:

pluginOptions {
    enabled = false // No spec will be generated
}

enabled = !project.hasProperty("skipOpenApi")

saveInBuild¶

Controls whether the spec is saved in the build/ directory.

saveInBuild = true // default

When true, the spec is saved to:

build/resources/main/openapi/openapi.yaml

When false and filePath is not set, it saves to:

src/main/resources/openapi/openapi.yaml

format¶

Sets the output format for the generated specification.

format = "yaml" // default

filePath¶

Custom absolute path for the generated specification.

filePath = null // default - uses saveInBuild setting

Override to save to a specific location:

pluginOptions {
    filePath = "${project.projectDir}/docs/api/openapi.yaml"
}

regenerationMode¶

Controls how the plugin handles incremental compilation.

regenerationMode = "strict" // default

strict (Default)¶

Always regenerates the full spec on every build:

regenerationMode = "strict"

Pros: Guarantees a complete and accurate specification

Cons: Disables incremental compilation benefits

Use for: CI/CD pipelines, production builds, any build where spec accuracy is critical

safe¶

Tracks source files containing @GenerateOpenApi and regenerates when they change:

regenerationMode = "safe"

Pros: Faster builds when editing non-route files

Cons: May miss body-only changes in route helper functions

Use for: Local development when you primarily edit @GenerateOpenApi annotated files

fast¶

Trusts Kotlin's incremental compilation completely:

regenerationMode = "fast"

Pros: Fastest possible builds

Cons: May produce incomplete specs during incremental builds

Use for: Rapid prototyping where you don't need an accurate spec

Environment-Based Configuration¶

Configure different options for different environments:

swagger {
    pluginOptions {
        // Use fast mode locally, strict in CI
        regenerationMode = if (System.getenv("CI") != null) "strict" else "safe"

        // Different output format for different environments
        format = findProperty("openapi.format")?.toString() ?: "yaml"
    }
}

Complete Reference¶