TypedRest.CodeGeneration.Kotlin 0.3.0

Code Generation for Kotlin

Generates Kotlin source code for TypedRest for the JVM clients from OpenAPI/Swagger documents.

dotnet add package TypedRest.CodeGeneration.Kotlin

Use this to build your own code generator. If you just want to generate a client for your API, use the command-line tool instead; it is built on this library.

Usage

var reader = new OpenApiStreamReader(new OpenApiReaderSettings().AddTypedRest());
var doc = reader.Read(File.OpenRead("myapi.yml"), out _);

foreach (var file in doc.GenerateTypedRestKotlin(new KotlinGenerationOptions("MyService")
{
    Namespace = "com.mycompany.myservice",
    GenerateDtos = true
}))
    file.WriteToDirectory("src/main/kotlin/");

GenerateTypedRestKotlin() uses the endpoints described by the document's x-typedrest extension, or infers them from the paths using TypedRest.CodeGeneration if there is no such extension.

The generated code needs the TypedRest artifacts on the classpath:

dependencies {
    implementation("net.typedrest:typedrest:<version>")

    // Only when generating DTOs for the default kotlinx serializer
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:<version>")
}

Add net.typedrest:typedrest-reactive as well if the document describes any polling or streaming endpoints.

The explicit kotlinx-serialization-json is easy to miss: TypedRest depends on it only as implementation, so it does not reach a consumer's compile classpath, and the kotlin("plugin.serialization") plugin adds the compiler plugin but no dependency. Without it the @Serializable and @SerialName annotations on the generated DTOs do not resolve.

Output

One file per generated type, in a directory matching its package. Namespace is the package for the endpoints, defaulting to the service name; DtoNamespace is the package for the DTOs, defaulting to a dtos subpackage of the endpoints.

Endpoints become open classes deriving from the TypedRest Impl classes and exposing their children as vals. They are open so that you can derive from them to add members of your own.

With GenerateInterfaces each generated endpoint also gets an interface, named the way TypedRest for the JVM names its own: the interface takes the plain name and the class beside it gets the Impl suffix.

interface ContactElementEndpoint : ElementEndpoint<Contact> {
    val note: ElementEndpoint<Note>
}

open class ContactElementEndpointImpl(referrer: Endpoint, relativeUri: URI)
    : ElementEndpointImpl<Contact>(referrer, relativeUri, Contact::class.java), ContactElementEndpoint {
    override val note: ElementEndpoint<Note> = ElementEndpointImpl(this, "./note", Note::class.java)
}

DTOs become data classes, and schemas with an enum become enum classes. A property the document does not mark as required is nullable and defaults to null; a required one gets no default, so a missing value is a compile error.

A $ref inside allOf is flattened into the type rather than becoming a base class. Every property is still present; only the inheritance relationship is lost.

Serializers

Serializer picks which annotations carry the wire names:

kotlinx.serialization is the default of EntryEndpoint itself, so a client generated for it passes no serializer at all. The others are passed explicitly in the generated entry endpoint constructor.

Generating for kotlinx requires the kotlin-serialization Gradle plugin in the consuming project — the @Serializable annotation does nothing without the compiler plugin that acts on it:

plugins {
    kotlin("plugin.serialization") version "<version>"
}

Extension points

GenerateTypedRestKotlin() takes an optional PatternRegistry controlling what is inferred, and an optional BuilderRegistry controlling what is emitted:

var files = doc.GenerateTypedRestKotlin(options, log, patterns, builders);

Both registries live in TypedRest.CodeGeneration.Jvm and are shared with the Java generator, so a builder you write once affects both. Implement IBuilder<TEndpoint> to change the code emitted for an endpoint kind, or derive from NamingStrategy to change how types and properties are named.

Related packages

• TypedRest.CodeGeneration.Jvm is the basis of this library and holds everything shared with the Java generator.
• TypedRest.CodeGeneration.Java does the same for Java.
• typedrest-codegen is a command-line tool that builds on this library and writes the generated code to disk.

Links

• Code generation documentation
• API documentation