README.md

Schema-Kenerator

Kotlin library to extract information from classes using reflection or kotlinx-serialization and generate schemas like json-schema or swagger-schemas from the resulting information.

Features

• extract information from classes using reflection or kotlinx-serialization
• supports nested types, inheritance, generics, annotations
• generate json-schema or swagger-schema
• add metadata using additional annotations (title, description, deprecation, subtypes, ...)
• supports annotations from Jackson, Swagger, Javax-Validations and Jakarta-Validations
• customizable and extendable

Installation

dependencies {
    implementation("io.github.smiley4:schema-kenerator-core:<VERSION>")
    // only for using reflection
    implementation("io.github.smiley4:schema-kenerator-reflection:<VERSION>")
    // only for using kotlinx-serialization
    implementation("io.github.smiley4:schema-kenerator-serialization:<VERSION>")
    // only for generating json-schemas
    implementation("io.github.smiley4:schema-kenerator-jsonschema:<VERSION>")
    // only for generating swagger-schemas
    implementation("io.github.smiley4:schema-kenerator-swagger:<VERSION>")
    // only for support of Jackson-annotations
    implementation("io.github.smiley4:schema-kenerator-jackson:<VERSION>")
   // only for support of javax and jakarta validation-annotations for swagger-schemas
   implementation("io.github.smiley4:schema-kenerator-validations-swagger:<VERSION>")
}

Documentation

Examples showcasing and explaining the functionalities and use cases of this project can be found here.

A wiki with documentation is available here.

Concept Overview

Data extraction and schema generation happens in several steps that can be grouped into the following phases:

1. Information extraction
   1. collect relevant types that need to be analyzed
   2. process types, i.e. extract information from each type and nested types
   3. enrich and modify extracted type data, e.g. with annotations
2. Schema generation
   1. generate individual schema for each type (and nested type)
   2. enrich and modify generated schemas, e.g. using annotations
   3. compile individual schemas into one final schema, either inlining all types or properly referencing them

Schema-Kenerator provides independent steps for each phase that can be chained together to achieve the desired result.

Example (json-schema & reflection)

class MyExampleClass(
    val someText: String,
    val someNullableInt: Int?,
    val someBoolList: List<Boolean>,
)

val jsonSchema = typeOf<MyExampleClass>()
    .processReflection()
    .generateJsonSchema()
    .withTitle(TitleType.SIMPLE)
    .compileInlining()
    .json
    .prettyPrint()

{
   "type": "object",
   "title": "MyExampleClass",
   "required": [ "someBoolList", "someText" ],
   "properties": {
     "someBoolList": {
       "type": "array",
       "title": "List<Boolean>",
       "items": {
         "type": "boolean",
         "title": "Boolean"
       }
     },
     "someNullableInt": {
       "type": "integer",
       "title": "Int",
       "minimum": -2147483648,
       "maximum": 2147483647
     },
     "someText": {
       "type": "string",
       "title": "String"
     }
   }
}

Example (swagger & kotlinx-serialization)

dependencies {
    implementation("io.github.smiley4:schema-kenerator-core:<VERSION>")
    implementation("io.github.smiley4:schema-kenerator-serialization:<VERSION>")
    implementation("io.github.smiley4:schema-kenerator-swagger:<VERSION>")
}

@Serializable
class MyExampleClass(
    val someText: String,
    val someNullableInt: Int?,
    val someBoolList: List<Boolean>,
)

val swaggerSchema: Schema<*> = typeOf<ClassWithSimpleFields>()
    .processKotlinxSerialization()
    .generateSwaggerSchema()
    .withTitle(TitleType.SIMPLE)
    .compileInlining()
    .swagger

{
  "title" : "MyExampleClass",
  "required" : [ "someBoolList", "someText" ],
  "type" : "object",
  "properties" : {
    "someText" : {
      "title" : "String",
      "type" : "string",
      "exampleSetFlag" : false
    },
    "someNullableInt" : {
      "title" : "Int",
      "type" : "integer",
      "format" : "int32",
      "exampleSetFlag" : false
    },
    "someBoolList" : {
      "title" : "ArrayList<Boolean>",
      "type" : "array",
      "exampleSetFlag" : false,
      "items" : {
        "title" : "Boolean",
        "type" : "boolean",
        "exampleSetFlag" : false
      }
    }
  },
  "exampleSetFlag" : false
}