Nikcio.OpenApiCodeGen 1.0.0

OpenAPI Code Generator

<p align="center"> <strong>A fast, opinionated C# code generator for OpenAPI specifications.</strong> </p>

<p align="center"> <a href="https://www.nuget.org/packages/Nikcio.OpenApiCodeGen"><img src="https://img.shields.io/nuget/v/Nikcio.OpenApiCodeGen.svg" alt="NuGet" /></a> <a href="https://www.nuget.org/packages/Nikcio.OpenApiCodeGen"><img src="https://img.shields.io/nuget/dt/Nikcio.OpenApiCodeGen.svg" alt="NuGet Downloads" /></a> <a href="https://github.com/Nikcio-labs/openapi-code-generator/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Nikcio-labs/openapi-code-generator.svg" alt="License" /></a> </p>

<p align="center"> <a href="https://nikcio-labs.github.io/openapi-code-generator">Documentation</a> • <a href="#installation">Installation</a> • <a href="#quick-start">Quick Start</a> • <a href="CHANGELOG.md">Changelog</a> </p>

OpenAPI Code Generator transforms OpenAPI 3.x specifications into clean, modern C# code — generating records, enums, and type aliases with full nullable reference type support and System.Text.Json serialization out of the box.

Features

• Modern C# output — Generates record types with init-only properties
• OpenAPI 3.x support — JSON and YAML specifications
• Nullable reference types — Full #nullable enable support
• System.Text.Json — Built-in [JsonPropertyName] and [JsonConverter] attributes
• String enums — Generates [JsonStringEnumConverter] backed enums
• Immutable collections — IReadOnlyList<T> and IReadOnlyDictionary<string, T> by default
• Composition support — Handles allOf, oneOf, and anyOf schemas
• URL input — Fetch and generate directly from remote OpenAPI specs
• Zero dependencies at runtime — Generated code only needs System.Text.Json

Installation

Install as a global .NET tool:

dotnet tool install --global Nikcio.OpenApiCodeGen

Or as a local tool in your project:

dotnet new tool-manifest
dotnet tool install Nikcio.OpenApiCodeGen

Quick Start

Generate C# models from a local spec file:

openapi-codegen petstore.yaml -o Models.cs

Generate from a remote URL with a custom namespace:

openapi-codegen https://petstore3.swagger.io/api/v3/openapi.json -o PetStore.cs -n MyApp.Models

Output to stdout:

openapi-codegen spec.yaml

CLI Reference

USAGE:
    openapi-codegen [OPTIONS] <input> [output]
    openapi-codegen --input <file-or-url> --output <file>

ARGUMENTS:
    <input>     Path or URL to an OpenAPI specification (JSON or YAML)
    [output]    Output file path (defaults to stdout)

OPTIONS:
    -i, --input <path>          Input OpenAPI spec file or URL
    -o, --output <path>         Output C# file path
    -n, --namespace <name>      C# namespace (default: GeneratedModels)
        --no-doc-comments       Disable XML doc comment generation
        --no-header             Disable auto-generated file header
        --no-default-non-nullable  Don't treat defaults as non-nullable
        --no-add-default-values     Don't add default values from OpenAPI to properties
        --mutable-arrays        Use List<T> instead of IReadOnlyList<T>
        --mutable-dictionaries  Use Dictionary<K,V> instead of IReadOnlyDictionary<K,V>
    -v, --version               Show version information
    -h, --help                  Show this help message

Library Usage

You can also reference the core library directly for programmatic code generation:

using OpenApiCodeGenerator;

var generator = new CSharpSchemaGenerator(new GeneratorOptions
{
    Namespace = "MyApp.Models",
    GenerateDocComments = true
});

string code = generator.GenerateFromFile("petstore.yaml");
File.WriteAllText("Models.cs", code);

Example Output

Given a simple Petstore OpenAPI spec, the generator produces:

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

#nullable enable

using System.Text.Json.Serialization;

namespace Generated.Petstore;

/// <summary>
/// Order Status
/// </summary>
[JsonConverter(typeof(JsonStringEnumConverter))]
public enum OrderStatus
{
    [JsonStringEnumMemberName("placed")]
    Placed,
    [JsonStringEnumMemberName("approved")]
    Approved,
    [JsonStringEnumMemberName("delivered")]
    Delivered
}

/// <summary>
/// pet status in the store
/// </summary>
[JsonConverter(typeof(JsonStringEnumConverter))]
public enum PetStatus
{
    [JsonStringEnumMemberName("available")]
    Available,
    [JsonStringEnumMemberName("pending")]
    Pending,
    [JsonStringEnumMemberName("sold")]
    Sold
}

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

    [JsonPropertyName("petId")]
    public long? PetId { get; init; }

    [JsonPropertyName("quantity")]
    public int? Quantity { get; init; }

    [JsonPropertyName("shipDate")]
    public DateTimeOffset? ShipDate { get; init; }

    /// <summary>
    /// Order Status
    /// </summary>
    [JsonPropertyName("status")]
    public OrderStatus? Status { get; init; }

    [JsonPropertyName("complete")]
    public bool? Complete { get; init; }

}

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

    [JsonPropertyName("name")]
    public string? Name { get; init; }

}

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

    [JsonPropertyName("username")]
    public string? Username { get; init; }

    [JsonPropertyName("firstName")]
    public string? FirstName { get; init; }

    [JsonPropertyName("lastName")]
    public string? LastName { get; init; }

    [JsonPropertyName("email")]
    public string? Email { get; init; }

    [JsonPropertyName("password")]
    public string? Password { get; init; }

    [JsonPropertyName("phone")]
    public string? Phone { get; init; }

    /// <summary>
    /// User Status
    /// </summary>
    [JsonPropertyName("userStatus")]
    public int? UserStatus { get; init; }

}

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

    [JsonPropertyName("name")]
    public string? Name { get; init; }

}

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

    [JsonPropertyName("name")]
    public required string Name { get; init; }

    [JsonPropertyName("category")]
    public Category? Category { get; init; }

    [JsonPropertyName("photoUrls")]
    public required IReadOnlyList<string> PhotoUrls { get; init; }

    [JsonPropertyName("tags")]
    public IReadOnlyList<Tag>? Tags { get; init; }

    /// <summary>
    /// pet status in the store
    /// </summary>
    [JsonPropertyName("status")]
    public PetStatus? Status { get; init; }

}

public record ApiResponse
{
    [JsonPropertyName("code")]
    public int? Code { get; init; }

    [JsonPropertyName("type")]
    public string? Type { get; init; }

    [JsonPropertyName("message")]
    public string? Message { get; init; }

}

Configuration Options

Contributing

Please see CONTRIBUTING.md for guidelines.

License

See the LICENSE file for details.