Schema Generation

Schemas are automatically generated from types using a schema generation function configured in the plugin configuration and uses schema-kenerator by default.

Pre-Defined Schema Generators

ReflectionKotlinx.Serialization

The (default) schema generator using reflection to analyze types and produce schemas. The result is closest to the result produced by serializers like Jackson.

install(OpenApi) {
    schemas {
        generator = SchemaGenerator.reflection { //(1)!
            //...(2)
        }
    }
}

1. Use the pre-defined schema generator using reflection to automatically generate schemas from types.
2. Configure the schema generator (optional).

More Information

API Reference

Schema generator using kotlinx.serialization to analyze types and produce schemas.

install(OpenApi) {
    schemas {
        generator = SchemaGenerator.kotlinx { //(1)!
            //...(2)
        }
    }
}

1. Use the pre-defined schema generator using kotlinx.serialization to automatically generate schemas from types.
2. Configure the schema generator (optional).

More Information

API Reference

Defining Custom Schemas for Types

Sometimes the schema generator does not produce the exact desired result for some types. See schema-kenerator for detailed information on how to modify schemas for types.

When using the pre-build schema generators, "Type Overwrites" can be used to completely replace the schema for a type with another schema.

ReflectionKotlinx.Serialization

install(OpenApi) {
    schemas {
        generator = SchemaGenerator.reflection {
            overwrite(SchemaGenerator.TypeOverwrites.LocalDateTime()) //(1)!
            overwrite(SchemaGenerator.TypeOverwrites.File()) //(2)!
            //...
        }
    }
}

1. Use a pre-defined schema for java.time.LocalDateTime instead of the auto-generated one.
2. Use a pre-defined schema for java.io.File instead of the auto-generated one.

install(OpenApi) {
    schemas {
        generator = SchemaGenerator.kotlinx {
            overwrite(SchemaGenerator.TypeOverwrites.LocalDateTime()) //(1)!
            overwrite(SchemaGenerator.TypeOverwrites.File()) //(2)!
            //...
        }
    }
}

1. Use a pre-defined schema for java.time.LocalDateTime instead of the auto-generated one.
2. Use a pre-defined schema for java.io.File instead of the auto-generated one.

More Information

API Reference for available type overwrites.

API Reference for interface to implement own type overwrites.

Custom Schema Generators

The schema generator can be completely replaced by an own implementation or by a different, non pre-built configuration.

schemas {
    generator = { type -> //(1)!
        TODO() //(2)!
    }
}

1. Input of the schema generation function is the type either as a (wrapped) KType or SerialDescriptor.
2. Generate the schema and return the result as a io.github.smiley4.schemakenerator.swagger.data.CompiledSwaggerSchema

Custom schema-kenerator "pipeline"

Using schema-kenerator to build a custom schema generation "pipeline".

schemas {
    generator = { type ->
        type
            .processReflection()
            .generateSwaggerSchema()
            .withTitle(TitleType.SIMPLE)
            .compileReferencingRoot()
    }
}

More Information

More information can be found in the wiki of the schema-kenerator project together with an overview of the additional required dependencies.