typedrest-codegen 0.3.0

Code Generation CLI

Command-line tool that automatically infers TypedRest Endpoints from patterns in OpenAPI/Swagger documents and generates source code for TypedRest clients.

Make sure you have the .NET SDK installed and run:

dotnet tool install -g typedrest-codegen

If you build your client with the .NET SDK, consider the source generator instead. It runs the same generator during compilation, without writing files to your source tree.

For a walkthrough see the usage guide.

generate

Generates a TypedRest client.

typedrest-codegen generate -f myapi.yml -o myclient/ -s MyService --generate-interfaces --generate-dtos

C#

The generated code derives from the TypedRest package, so run dotnet add package TypedRest in the consuming project.

Unlike the source generator, interfaces and DTOs are opt-in here. Generated endpoints reference the DTO types by name, so without --generate-dtos you have to provide those types yourself.

Use --generate-entry-constructor false when the entry endpoint needs a custom error handler or default headers. The class and its base type are still generated, but the constructor is left for you to write in a partial class.

--serializer picks which attributes carry the wire names on the generated DTOs:

typedrest-codegen generate -f myapi.yml -o myclient/ -s MyService --generate-dtos --serializer system-text-json

This has to match the serializer the endpoint is configured with at runtime. The two read entirely different attributes, so a DTO annotated for one silently falls back to its C# member names under the other, changing the wire format without any error.

[JsonStringEnumMemberName] requires .NET 9 or later. It is what JsonStringEnumConverter reads; System.Text.Json ignores [EnumMember] entirely.

Java

typedrest-codegen generate -l java -f myapi.yml -o src/main/java/ -s MyService -n com.mycompany.myservice --generate-dtos

Prefer the Kotlin generator if you can: TypedRest for the JVM is written in Kotlin, so that is the lower-friction direction. Use this one when your own source is Java.

The layout matches the Kotlin generator's. Endpoints expose their children as JavaBean getters over private final fields, e.g. client.getContacts().get("1337"). DTOs become plain classes with public fields, a no-argument constructor and a full one.

--generate-interfaces also gives each generated endpoint an interface: the interface takes the plain name and the class beside it gets the Impl suffix. Without it there is no interface and the class keeps the plain name.

Properties the document does not require are annotated with JSpecify's @Nullable, so that Kotlin consumers get real null safety instead of platform types. Add org.jspecify:jspecify to the consuming project, or drop the annotations by generating Kotlin instead.

--serializer picks jackson (default) or moshi. kotlinx is rejected here: kotlinx.serialization generates its serializers with a Kotlin compiler plugin and cannot handle a class written in Java.

Kotlin

typedrest-codegen generate -l kotlin -f myapi.yml -o src/main/kotlin/ -s MyService -n com.mycompany.myservice --generate-dtos

The generated code derives from TypedRest for the JVM, so add net.typedrest:typedrest to the consuming project — plus net.typedrest:typedrest-reactive if the document describes any polling or streaming endpoints.

One file per type, in a directory matching its package, so --output is the source root (src/main/kotlin/) rather than the package directory. --namespace is the package for the endpoints and --dto-namespace the one 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. DTOs become data classes, and schemas with an enum become enum classes. Optional properties are nullable and default to null; required ones get no default, so a missing value is a compile error.

--generate-interfaces also gives each generated endpoint an interface: the interface takes the plain name and the class beside it gets the Impl suffix. Without it there is no interface and the class keeps the plain name.

--serializer picks kotlinx (default), jackson or moshi. kotlinx.serialization is what EntryEndpoint itself defaults to, so a client generated for it passes no serializer at all; the others are passed explicitly.

Generating DTOs for kotlinx needs both the kotlin("plugin.serialization") Gradle plugin and an explicit org.jetbrains.kotlinx:kotlinx-serialization-json dependency: TypedRest depends on it only as implementation, so it does not reach your compile classpath, and the plugin adds the compiler plugin but no dependency.

TypeScript

typedrest-codegen generate -l typescript -f myapi.yml -o src/myclient/ -s MyService --generate-dtos

The generated code imports from the typedrest package, so run npm install typedrest in the consuming project.

Each generated type gets its own file, plus an index.ts re-exporting all of them. Here --namespace and --dto-namespace are directories relative to --output rather than namespaces, defaulting to the output directory itself and to dtos. Dotted values such as MyCompany.MyService become nested directories.

Endpoints become classes deriving from the TypedRest endpoint types and exposing their children as getters. DTOs become interfaces whose properties keep the exact name used on the wire, because TypedRest for TypeScript deserializes with JSON.parse() and a cast and so has no way to map a property to a differently named field. Schemas with an enum become literal union type aliases.

--serializer has no effect here, for the same reason: there is no serializer to choose and nothing to annotate.

pattern

Runs only the inference step and writes the result back into the document as an x-typedrest extension, for inspecting or hand-editing what the tool infers.

typedrest-codegen pattern -f myapi.yml -o myapi-annotated.yml

When a document already contains an x-typedrest extension, generate uses it as-is instead of re-running the inference.

Links

• Code generation documentation