Swagger Client Generator

Work in Progress — Core generation works end-to-end; see Known Limitations for what isn't supported yet.

A Kotlin-based code generator that produces type-safe API clients for Kotlin and Swift from OpenAPI 3.0 YAML specifications. Point it at a spec, get a ready-to-use Retrofit interface and Swift async/await class out the other side.

Design

The project is split into three modules:

parser/      Multiplatform (JVM/macOS/Linux) OpenAPI 3.0 YAML/JSON deserializer.
             Produces a typed in-memory model of the spec.

typed/       Transforms the raw parsed model into an intermediate representation
             (Routes, Models, Parameters) that generators consume. This is where
             unsupported patterns are detected and skipped with warnings.

generator/   Language-specific code emitters.
             - RetrofitGenerator  →  Kotlin interface + data classes (via KotlinPoet)
             - SwiftGeneratorSimple  →  Swift class + structs (via SwiftPoet)
             Output lands in output/{ApiName}/{Version}/kotlin/ and .../swift/

The pipeline is: YAML → parser → raw OpenAPI model → typed (OpenAPITransformer) → routes/models → generator → source files.

Output structure

output/
└── {ApiName}/
    └── {Version}/
        ├── kotlin/
        │   ├── build.gradle.kts      (ready-to-publish Gradle project)
        │   └── src/main/kotlin/
        │       ├── {Name}RetrofitApi.kt
        │       └── model/*.kt
        └── swift/
            ├── Package.swift         (SPM manifest)
            └── Sources/{Name}/
                ├── {Name}.swift      (API class with async/await methods)
                └── Models.swift      (Codable structs/enums)

CI

GitHub Actions runs on every push to develop and every PR:

1. Unit Tests — ./gradlew test (parser module)
2. Generate API Clients — generates all schemas in schemas/, uploads output/ as a downloadable artifact

Schemas used (all public):

Schema	Complexity	Notable patterns
Petstore	Small (8 models, 14 ops)	Path/query params, enums
TVmaze	Small (13 models, 20 ops)	Nested embeds, auth
Giphy	Small (27 models, 10 ops)	Deeply nested image schemas
Wordnik	Medium (26 models, 9 ops)	*/* content type, array responses
Spotify	Large (215 models, 72 ops)	Complex allOf, oneOf, union types

Quick start

# Build
./gradlew build

# Generate a client
./gradlew :generator:generateApiClient -Pyaml=schemas/petstore/swagger.yaml

# Generate all demo schemas
for s in schemas/*/swagger.yaml; do
  ./gradlew :generator:generateApiClient -Pyaml=$s --no-daemon
done

Output lands in output/ (gitignored).

Type mappings

OpenAPI	Kotlin	Swift
string	String	String
integer	Int	Int
number	Double	Double
boolean	Boolean	Bool
array	List<T>	[T]
object	data class	struct

Known limitations

These patterns are detected and skipped with a warning rather than failing the build:

• XML request bodies — Petstore's PUT /pet, POST /pet, etc. declare application/xml bodies; XML serialization is not implemented
• additionalProperties + properties combined — Spotify uses this pattern on ~16 endpoints; mixed open/closed objects aren't modelled yet
• Missing operationId — TVmaze has inline request body schemas on endpoints without an operationId; the generator needs one to name the generated class
• Null-type schemas — Wordnik has component schemas with no type field; the transformer doesn't have a fallback for fully untyped objects

Project structure

generator/   Main CLI task + RetrofitGenerator + SwiftGeneratorSimple
parser/      Multiplatform OpenAPI deserializer (KAML + kotlinx.serialization)
typed/       OpenAPITransformer, Route/Model IR, NamingContext
templates/   Gradle and SPM project templates copied into output
schemas/     Demo OpenAPI specs (public APIs)
petstore/    Reference Petstore spec (OpenAPI 3.0.4)
playground/  Example of consuming a generated Kotlin client

Running tests

./gradlew test