Configuration

OpenAPI Code Generator provides a rich set of options to customize the generated C# output. Options can be set via CLI flags or programmatically through GeneratorOptions.

Options Overview

Option	CLI Flag	Default	Description
Namespace	-n, --namespace	GeneratedModels	C# namespace for generated types
IncludeSchemas	--include-schema	null	Generate only selected schemas and their dependencies
GenerateDocComments	--no-doc-comments	true	Include XML doc comments
GenerateFileHeader	--no-header	true	Auto-generated file header
DefaultNonNullable	--no-default-non-nullable	true	Defaults as non-nullable
AddDefaultValuesToProperties	--no-add-default-values	true	Add default values from OpenAPI to properties
UseImmutableArrays	--mutable-arrays	true	Use IReadOnlyList<T>
UseImmutableDictionaries	--mutable-dictionaries	true	Use IReadOnlyDictionary
InlinePrimitiveTypeAliases	--inline-type-aliases	false	Inline primitive aliases instead of emitting wrapper types

Namespace

Controls the C# namespace for all generated types.

CLI:

openapi-codegen spec.yaml -o Models.cs -n MyApp.Api.Models

Library:

new GeneratorOptions { Namespace = "MyApp.Api.Models" }

Output:

namespace MyApp.Api.Models;

Included Schemas

Restricts generation to a named subset of component schemas while automatically bringing along referenced dependencies.

CLI: Repeat --include-schema for each root schema you want to generate.

openapi-codegen spec.yaml -o Models.cs --include-schema User --include-schema Address

Library:

new GeneratorOptions
{
    IncludeSchemas = ["User", "Address"]
}

If User references Address, including only User is enough to generate both.

XML Doc Comments

When enabled, OpenAPI description fields are converted to XML doc comments on the generated types and properties.

CLI: Enabled by default. Disable with --no-doc-comments.

Example output with doc comments:

/// <summary>
/// A pet available in the store
/// </summary>
public record Pet
{
    /// <summary>
    /// The unique identifier for the pet
    /// </summary>
    [JsonPropertyName("id")]
    public long Id { get; init; }
}

Without doc comments:

public record Pet
{
    [JsonPropertyName("id")]
    public long Id { get; init; }
}

File Header

When enabled, adds an auto-generated comment header to prevent accidental manual editing:

// <auto-generated>
// This file was auto-generated by OpenApiCodeGenerator.
// Do not make direct changes to the file.
// </auto-generated>

CLI: Enabled by default. Disable with --no-header.

Default Non-Nullable

When enabled, properties with default values in the OpenAPI spec are treated as non-nullable.

CLI: Enabled by default. Disable with --no-default-non-nullable.

Add Default Values to Properties

When enabled, properties with default values in the OpenAPI spec will have those default values added to the generated C# properties.

CLI: Enabled by default. Disable with --no-add-default-values.

Immutable Collections

Arrays

Controls whether array types use IReadOnlyList<T> (immutable) or List<T> (mutable).

CLI: Immutable by default. Use --mutable-arrays for List<T>.

Immutable (default):

public IReadOnlyList<string> Tags { get; init; }

Mutable:

public List<string> Tags { get; init; }

Dictionaries

Controls whether dictionary types use IReadOnlyDictionary<string, T> or Dictionary<string, T>.

CLI: Immutable by default. Use --mutable-dictionaries for mutable.

Immutable (default):

public IReadOnlyDictionary<string, object> Metadata { get; init; }

Mutable:

public Dictionary<string, object> Metadata { get; init; }

Primitive Type Aliases

Controls whether primitive component aliases are emitted as wrapper structs or inlined to their underlying primitive types.

CLI: Wrapper aliases by default. Use --inline-type-aliases to inline them.

Library:

new GeneratorOptions { InlinePrimitiveTypeAliases = true }

Default output:

using System.Text.Json;
using System.Text.Json.Serialization;

file interface IOpenApiGeneratedTypeAlias<TSelf, TValue>
    where TSelf : struct, IOpenApiGeneratedTypeAlias<TSelf, TValue>
{
    static abstract TSelf Create(TValue value);

    TValue Value { get; }
}

file sealed class OpenApiGeneratedTypeAliasJsonConverter<TAlias, TValue> : JsonConverter<TAlias>
    where TAlias : struct, IOpenApiGeneratedTypeAlias<TAlias, TValue>
{
    public override TAlias Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        TValue value = JsonSerializer.Deserialize<TValue>(ref reader, options)!;
        return TAlias.Create(value);
    }

    public override void Write(Utf8JsonWriter writer, TAlias value, JsonSerializerOptions options)
    {
        JsonSerializer.Serialize(writer, value.Value, options);
    }
}

[JsonConverter(typeof(OpenApiGeneratedTypeAliasJsonConverter<AlertCreatedAt, DateTimeOffset>))]
public readonly record struct AlertCreatedAt(DateTimeOffset Value) : IOpenApiGeneratedTypeAlias<AlertCreatedAt, DateTimeOffset>
{
    public static AlertCreatedAt Create(DateTimeOffset value) => new(value);
}

Inline output:

[JsonPropertyName("createdAt")]
public required DateTimeOffset CreatedAt { get; init; }