Generation Pipeline

AutoSDK processes OpenAPI specifications through a multi-stage pipeline that produces fully typed, AOT-compatible C# code.

Pipeline Overview

OpenAPI/AsyncAPI Spec
        │
        ▼
   ┌─────────┐
   │  Parse   │  Read and validate the spec (OpenAPI 3.0/3.1)
   └────┬─────┘
        │
        ▼
   ┌──────────────┐
   │ Data.Prepare  │  Normalize schemas, resolve refs, build type graph
   └──────┬───────┘
        │
        ▼
   ┌──────────────┐
   │ SchemaContext │  Map OpenAPI types → C# types, handle naming
   └──────┬───────┘
        │
        ▼
   ┌──────────────┐
   │  Code Gen    │  Emit C# source files from templates
   └──────┬───────┘
        │
        ▼
   Generated/*.g.cs

Stage 1: Parse

The spec is parsed from JSON or YAML into an in-memory representation. AutoSDK supports:

• OpenAPI 3.0.x and 3.1.x
• AsyncAPI 2.x (for WebSocket generation)
• Remote $ref resolution
• Configurable error/warning handling (--ignore-openapi-errors)

Stage 2: Data.Prepare

This is the core normalization stage:

• Reference resolution — All $ref pointers are resolved to concrete schemas
• Type graph construction — Builds a graph of all types and their relationships
• Discriminator analysis — Identifies oneOf/anyOf discriminators (with --compute-discriminators)
• Operation extraction — Maps paths + methods to operations with parameters and responses
• Security scheme mapping — Associates auth requirements with operations

Stage 3: SchemaContext

Maps the normalized data to C# concepts:

• Type mapping — string → string, integer → int, number → double, etc.
• Naming — Applies naming conventions (PascalCase, collision resolution, ClsCompliantEnumPrefix)
• Enum generation — Creates C# enums from enum schemas with optional x-enum-varnames
• Model generation — Creates classes/records/structs based on ModelStyle
• Nullable handling — Maps OpenAPI nullable: true to C# nullable reference types

Stage 4: Code Generation

Emits C# source files using string templates:

• Client classes — HTTP client with typed methods for each operation
• Model classes — Request/response types, enums, converters
• JSON serialization — JsonSerializerContext with [JsonSerializable] attributes
• Polyfills — Compatibility shims for older target frameworks
• Constructors — Auth-aware constructors based on security schemes

File Naming

Generated files use the .g.cs suffix to distinguish them from hand-written code:

Generated/
├── MyApiClient.g.cs                    # HTTP client
├── MyApiClient.Models.g.cs             # All model types (single-file mode)
├── MyApiClient.Constructors.Bearer.g.cs # Auth constructors
├── SourceGenerationContext.g.cs         # JSON serializer context
└── Polyfills.g.cs                      # Framework compatibility

CLI vs Source Generator

Both modes use the same pipeline. The difference is the entry point: