OpenApiSourceGenerator 0.5.1-beta

OpenApiSourceGenerator

A straightforward C# source generator that generates strongly-typed C# classes from OpenAPI specifications (OpenAPI 3.x) at compile time. No additional build steps or tools required!

Features

• ✨ Compile-time code generation - Classes are generated automagically during build
• 🚀 Zero runtime overhead - All code generation happens at compile time
• 📝 OpenAPI 3.x support - Reads YAML and JSON OpenAPI specifications
• Built on top of Microsoft.OpenApi
• System.Text.Json compatible

Installation

Install via NuGet Package Manager:

dotnet add package OpenApiSourceGenerator

Or via Package Manager Console:

Install-Package OpenApiSourceGenerator

Getting Started

1. Add your OpenAPI specification file to your project (YAML or JSON format):

   openapi/
   └── openapi.yaml
   

2. Ensure the file is included in your project with AdditionalFiles:

   <ItemGroup>
     <AdditionalFiles Include="openapi\openapi.yaml" />
   </ItemGroup>
   

3. Build your project - Classes will be automatically generated!

Usage Example

Given an OpenAPI specification:

openapi: 3.0.0
info:
  title: Pet Store API
  version: 1.0.0
components:
  schemas:
    Pet:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        status:
          $ref: '#/components/schemas/PetStatus'
    PetStatus:
      type: string
      enum:
      - available
      - pending
      - sold

The generator will create:

public class Pet
{
    public int Id { get; set; }
    public string Name { get; set; }
    public PetStatus Status { get; set; }
}

public enum PetStatus
{
    Available,
    Pending,
    Sold
}

Use the generated classes in your code:

var pet = new Pet
{
    Id = 1,
    Name = "Fluffy",
    Status = PetStatus.Available
};

Known Limitations

The following OpenAPI features are currently not supported or only partially supported. Schemas that use these features will either be silently skipped or cause a build-time NotImplementedException, which surfaces as a Roslyn generator diagnostic (CS8785).

Feature Support Matrix

Enum Generation

OpenAPI enum schemas generate C# enum declarations. Top-level component enums use the schema name, referenced enum properties use that generated type, and inline property enums generate a separate enum named after the containing schema and property, such as PetStatus for a status enum inside Pet. If that name is already used by another generated type, a numeric suffix is appended, such as PetStatus2.

String enum values are converted to PascalCase member names by removing non-alphanumeric separators. If multiple values normalize to the same member name, a numeric suffix is appended to keep names stable and unique. Non-negative integer enum values generate members named Value{number}, while negative values use Negative{magnitude}; all integer members have explicit numeric assignments. For example, 5 becomes Value5 = 5 and -5 becomes Negative5 = -5; values outside the int range use a long enum backing type.

Generated string enums use System.Text.Json.Serialization.JsonStringEnumConverter with JsonStringEnumMemberNameAttribute to preserve the original OpenAPI wire values.

Nullable enum schemas follow the current nullable limitation: generated enum properties are not emitted as nullable, and OAS 3.1 null unions remain unsupported.

Format Support

The following type + format combinations map to more precise C# types. Any other format value (including none) falls back to the base type mapping shown in parentheses.

DateTimeOffset and Guid are emitted as globally qualified names (global::System.DateTimeOffset / global::System.Guid) so a component schema with a colliding name (e.g. a schema named Guid) cannot shadow the framework type.

NotImplementedException Scenarios

The following schema patterns will cause the generator to throw a NotImplementedException during compilation, which surfaces as a CS8785 diagnostic:

• A property or schema with type: null
• An array property (type: array) without an items definition
• An array items schema that is not a primitive type or an object reference (e.g. items: { type: array })

Workarounds

Until full support is added, consider the following workarounds:

• format: For format values not listed in Format Support, post-process the generated code to use the required property type.
• nullable: Avoid using type: null or OAS 3.1 null union types in schemas until support is added in #88.
• oneOf/anyOf/allOf: Replace composition with explicit property duplication in your spec, or define types manually.
• additionalProperties: Define dictionary properties manually.
• Build-time failures: If the generator encounters an unsupported schema, it throws a NotImplementedException that surfaces as a CS8785 diagnostic, failing the build. Remove or exclude the problematic schema(s) from your spec until support is available.

Configuration

Place OpenAPI files in your project and mark them as AdditionalFiles:

<ItemGroup>
  <AdditionalFiles Include="**\*.yaml" />
  <AdditionalFiles Include="**\openapi.json" />
</ItemGroup>

Requirements

• Consuming projects must target .NET 10 or higher.
• The source generator assembly targets .NET Standard 2.0 for compiler/analyzer loadability, but the generated code uses modern .NET APIs.

How It Works

This package uses Roslyn Source Generators and Microsoft.OpenApi to analyze OpenAPI specification files during compilation and generate corresponding C# classes. The generated code is added directly to your compilation, providing IntelliSense support and compile-time type checking.

Support

• 📖 Documentation
• 🐛 Report Issues
• 💬 Discussions

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.