Argon.Extensions.OpenApi

OpenApi extensions designed for Argon services

📦 Installation

dotnet add package Argon.Extensions.OpenApi

✨ Features

EnumSchemaTransformer

A schema transformer that automatically converts enum types to string representations in OpenAPI documentation, respecting your JSON serialization naming policies.

Characteristics:

• Automatic transformation of enum types to string schemas
• Support for nullable enums
• Respects JsonSerializerOptions naming policies (e.g., camelCase, PascalCase)
• Seamless integration with ASP.NET Core OpenAPI

🚀 Usage

Registering the transformer

using Argon.Extensions.OpenApi.Transformers;

var builder = WebApplication.CreateBuilder(args);

// Add OpenAPI services with enum transformer
builder.Services.AddOpenApi(options =>
{
    options.AddSchemaTransformer<EnumSchemaTransformer>();
});

var app = builder.Build();

app.MapOpenApi();
app.Run();

Example with enums

public enum UserRole
{
    Administrator,
    Manager,
    Employee,
    Guest
}

public class User
{
    public string Name { get; set; }
    public UserRole Role { get; set; }
    public UserRole? OptionalRole { get; set; }
}

The generated OpenAPI schema will represent enums as strings with the configured naming policy:

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "role": {
      "type": "string",
      "enum": ["administrator", "manager", "employee", "guest"]
    },
    "optionalRole": {
      "type": "string",
      "enum": ["administrator", "manager", "employee", "guest"]
    }
  }
}

With custom naming policy

builder.Services.Configure<JsonOptions>(options =>
{
    options.SerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
});

The transformer will automatically apply the naming policy to enum values.

📝 API Reference

EnumSchemaTransformer

Implements IOpenApiSchemaTransformer to transform enum schemas.

Constructor:

• EnumSchemaTransformer(IOptions<JsonOptions> jsonOptions) : Initializes the transformer with JSON options

Methods:

• TransformAsync(OpenApiSchema schema, OpenApiSchemaTransformerContext context, CancellationToken cancellationToken) : Transforms enum schemas to string type with enum values

🔗 Links

• Back to main project
• NuGet Package