NativeOpenApi 1.8.2

NativeOpenApi

OpenAPI 3.1 primitives for Native AOT .NET 10 — document loading, linting, merging, HTML rendering, and a catalog of UX attributes consumed by NativeLambdaRouter.SourceGenerator.OpenApi.

• Version: 1.8.2
• Target: net10.0
• Namespace root: Native.OpenApi
• AOT: zero runtime reflection; serialization through source-generated contexts

API surface at a glance

Attributes — Native.OpenApi.Attributes

Wave 1 (v1.7.0)

Navigation (v1.8.0) — assembly-level

Operation richness (v1.8.0) — class/struct

Schema richness (v1.8.0)

DataAnnotations ([Required], [StringLength], [MinLength], [MaxLength], [Range], [RegularExpression]) are also read automatically when present on properties.

Polymorphism (v1.8.0) — class

C# inheritance is auto-detected — no attribute needed for allOf on subclass schemas.

Document-level (v1.8.0) — assembly

Structural (v1.8.0) — class/struct (multi-use unless noted)

Structural (v1.8.0) — assembly

Fluent extension — Native.OpenApi.Extensions

Models — Native.OpenApi.Models

Rendering — Native.OpenApi.Rendering

Core classes

Installation

dotnet add package NativeOpenApi

Quick reference — Wave 1 (v1.7.0)

Hide endpoints from docs — F01

[HideFromDocs("internal ops endpoint")]
public sealed record InternalHealthCommand(string Secret);

Or at the route level (handy when the same command is mapped to several paths and only one should be hidden):

using Native.OpenApi.Extensions;

routes.MapGet<ListUsersCommand, ListUsersResponse>("/v1/admin/internal/users", ...)
      .ExcludeFromDocs();

Effect: the operation never appears in paths:. If every operation on a path is hidden, the path itself is dropped.

Deprecation — F03

[Deprecated(
    sunset: "2026-12-31",
    alternative: "POST /v2/orders",
    reason: "v1 doesn't support split payments.")]
public sealed record CreateOrderV1Command(...);

Emits:

deprecated: true
x-sunset: "2026-12-31"
x-swepay-alternative: "POST /v2/orders"
x-swepay-deprecation-reason: "v1 doesn't support split payments."

Named examples — F09

[ApiExample(
    name: "happy-path",
    summary: "Simple order with 1 item",
    RequestJson = "examples/create-order/happy.json",
    ResponseStatus = 201,
    ResponseJson = "examples/create-order/happy-response.json")]
[ApiExample(
    name: "validation-error",
    summary: "Invalid CNPJ",
    ResponseStatus = 422,
    ResponseJson = "examples/create-order/invalid-cnpj.json")]
public sealed record CreateOrderCommand(...);

Examples reference their JSON payload through externalValue (inline payload reading is a Wave 2 follow-up — see docs/CHANGELOG.md).

Error catalog — F12

Declare once:

public static class SwepayErrors
{
    [ErrorDefinition(
        code: "PAYMENT_INSUFFICIENT_FUNDS",
        httpStatus: 402,
        userMessage: "Saldo insuficiente no método de pagamento.",
        recovery: "Tente outro método de pagamento ou adicione saldo.",
        DocUrl = "https://docs.swepay.com.br/errors/PAYMENT_INSUFFICIENT_FUNDS")]
    public const string PaymentInsufficientFunds = "PAYMENT_INSUFFICIENT_FUNDS";
}

Wire on commands:

[ErrorCatalog(typeof(SwepayErrors))]
public sealed record CreatePaymentCommand(...);

Emits at document root:

x-swepay-error-catalog:
  - code: "PAYMENT_INSUFFICIENT_FUNDS"
    httpStatus: 402
    userMessage: "Saldo insuficiente no método de pagamento."
    recovery: "Tente outro método de pagamento ou adicione saldo."
    docUrl: "https://docs.swepay.com.br/errors/PAYMENT_INSUFFICIENT_FUNDS"

Per operation (the generator slices only codes whose httpStatus matches a declared response on that operation):

x-swepay-errors:
  - "PAYMENT_INSUFFICIENT_FUNDS"

Canonical problem+json schema — F13

When any operation advertises application/problem+json without a typed body, the generator injects:

components:
  schemas:
    SwepayProblemDetails:
      type: object
      properties: { type, title, status, detail, instance, code, recovery, requestId }
      required: [type, title, status, detail, code, recovery, requestId]

Two ways to opt in:

// (a) fluent — no typed body
routes.MapPost<CreateOrderCommand, CreateOrderResponse>("/v1/orders", ...)
      .ProducesProblem(422);

// (b) handler attribute — null responseType
public sealed class CreateOrderHandler : IRequestHandler<CreateOrderCommand, CreateOrderResponse>
{
    [ApiResponse(422, null, "application/problem+json")]
    public ValueTask<CreateOrderResponse> Handle(...) => ...;
}

Renderer options — F15 / F16 / F17

using Native.OpenApi;
using Native.OpenApi.Rendering;

var options = new OpenApiRendererOptions
{
    Branding = new OpenApiBrandingOptions
    {
        PrimaryColor = "#0A2540",
        AccentColor  = "#00D4AA",
        LogoUrl      = "https://cdn.swepay.com.br/brand/logo-dark.svg",
        FaviconUrl   = "https://cdn.swepay.com.br/brand/favicon.ico",
        FontFamily   = "Inter, Roboto, sans-serif"
    },
    Footer = new OpenApiFooterOptions
    {
        StatusUrl     = "https://status.swepay.com.br",
        SupportUrl    = "https://docs.swepay.com.br/support",
        ChangelogUrl  = "https://docs.swepay.com.br/changelog",
        SlaUrl        = "https://docs.swepay.com.br/sla",
        TermsUrl      = "https://docs.swepay.com.br/terms"
    },
    EnableMermaid        = true,   // F17 — render fenced ```mermaid blocks as SVG
    MermaidFromLocalAsset = false  // true for air-gapped deployments (serves ./assets/mermaid.min.js)
};

var renderer = new OpenApiHtmlRenderer();
var redocHtml  = renderer.RenderRedoc ("/docs/openapi.json", "My API", options);
var scalarHtml = renderer.RenderScalar("/docs/openapi.json", "My API", options);

The legacy RenderRedoc(spec, title) / RenderScalar(spec, title) overloads are preserved (RFC principle O5).

Mermaid in descriptions — any fenced ```mermaid block inside summary/description text becomes inline SVG when EnableMermaid = true. Example description body:

## Flow

```mermaid
flowchart LR
  A[1. Create realm] --> B[2. Register client] --> C[3. Issue token]
```

Quick reference — v1.8.0

Tag groups and tag metadata

// ApiDocumentation.cs (assembly-level declarations)
[assembly: OpenApiInfo(
    Description    = "Marketplace API — manage items, subscriptions and payments.",
    Summary        = "Marketplace API",
    TermsOfService = "https://example.com/terms",
    ContactName    = "API Support",
    ContactEmail   = "api@example.com",
    LicenseName    = "Apache 2.0",
    LicenseUrl     = "https://www.apache.org/licenses/LICENSE-2.0")]

[assembly: OpenApiServer("https://api.example.com",         Description = "Production")]
[assembly: OpenApiServer("https://sandbox.api.example.com", Description = "Sandbox")]

[assembly: OpenApiExternalDocs("https://docs.example.com", Description = "Developer guide")]

[assembly: TagMetadata("Orders",
    Description  = "Operations related to order lifecycle — creation, updates and cancellation.",
    DisplayName  = "Order Management",
    ExternalDocsUrl         = "https://docs.example.com/orders",
    ExternalDocsDescription = "Order domain guide")]

[assembly: TagGroup("Commerce",       new[] { "Orders", "Products" })]
[assembly: TagGroup("Administration", new[] { "Users",  "Roles"    })]

Emits:

externalDocs:
  description: "Developer guide"
  url: "https://docs.example.com"
tags:
  - name: Orders
    description: "Operations related to order lifecycle — creation, updates and cancellation."
    x-displayName: "Order Management"
    externalDocs:
      description: "Order domain guide"
      url: "https://docs.example.com/orders"
x-tagGroups:
  - name: Commerce
    tags: [Orders, Products]
  - name: Administration
    tags: [Users, Roles]

Code samples, badges and stability

[CodeSample("curl",
    source: """
    curl -X POST https://api.example.com/v1/orders \
         -H "Authorization: Bearer {token}" \
         -H "Content-Type: application/json" \
         -d '{"customerId":"cus_123","amount":49.90}'
    """,
    Label = "cURL")]
[CodeSample("csharp",
    source: "var resp = await http.PostAsJsonAsync(\"/v1/orders\", cmd);",
    Label = "C# (HttpClient)")]
[OperationBadge("beta",     Position = "after", Color = "#e5a505")]
[OperationBadge("internal", Color    = "#888")]
[ScalarStability(Stability.Experimental)]
public sealed record CreateOrderCommand(string CustomerId, decimal Amount);

Emits:

x-codeSamples:
  - lang: curl
    label: "cURL"
    source: |
      curl -X POST https://api.example.com/v1/orders \
           -H "Authorization: Bearer {token}" \
           -H "Content-Type: application/json" \
           -d '{"customerId":"cus_123","amount":49.90}'
  - lang: csharp
    label: "C# (HttpClient)"
    source: "var resp = await http.PostAsJsonAsync(\"/v1/orders\", cmd);"
x-badges:
  - name: beta
    position: after
    color: "#e5a505"
  - name: internal
    color: "#888"
x-scalar-stability: experimental

Polymorphic payment method (oneOf + discriminator)

[OpenApiDiscriminator("kind")]
[OpenApiSubType(typeof(CreditCardPayment), "credit_card")]
[OpenApiSubType(typeof(PixPayment),        "pix")]
public abstract class PaymentMethod
{
    public string Kind { get; set; } = "";
}

public sealed class CreditCardPayment : PaymentMethod
{
    public string CardToken { get; set; } = "";
    public int    Installments { get; set; }
}

public sealed class PixPayment : PaymentMethod
{
    public string PixKey { get; set; } = "";
}

Emits:

components:
  schemas:
    PaymentMethod:
      oneOf:
        - $ref: '#/components/schemas/CreditCardPayment'
        - $ref: '#/components/schemas/PixPayment'
      discriminator:
        propertyName: kind
        mapping:
          credit_card: '#/components/schemas/CreditCardPayment'
          pix:         '#/components/schemas/PixPayment'
    PaymentMethod__Core:
      type: object
      properties:
        kind:
          type: string
    CreditCardPayment:
      allOf:
        - $ref: '#/components/schemas/PaymentMethod__Core'
        - type: object
          properties:
            cardToken:
              type: string
            installments:
              type: integer
              format: int32
    PixPayment:
      allOf:
        - $ref: '#/components/schemas/PaymentMethod__Core'
        - type: object
          properties:
            pixKey:
              type: string

Scalar viewer configuration

var options = new OpenApiRendererOptions
{
    Branding = new OpenApiBrandingOptions { PrimaryColor = "#0A2540", LogoUrl = "https://cdn.example.com/logo.svg" },
    ScalarViewer = new OpenApiScalarViewerOptions
    {
        Theme                      = "midnight",
        DarkMode                   = true,
        Layout                     = "sidebar",
        HideModels                 = false,
        HideDownloadButton         = false,
        HideSidebar                = false,
        HideTestRequestButton      = false,
        DefaultHttpClientTargetKey = "Shell",
        DefaultHttpClientClientKey = "curl"
        // LocalAssetPath = "./assets/scalar.js"  // air-gap only
    }
};

var html = renderer.RenderScalar("/docs/openapi.yaml", "My API", options);

Minimal document pipeline

1. Loader

public class MyOpenApiDocumentLoader : OpenApiDocumentLoaderBase
{
    public MyOpenApiDocumentLoader(OpenApiResourceReader reader) : base(reader) { }

    public override IReadOnlyList<OpenApiDocumentPart> LoadCommon() => new[]
    {
        Load("common-schemas",   "openapi/common/schemas.yaml"),
        Load("common-responses", "openapi/common/responses.yaml"),
        Load("common-security",  "openapi/common/security.yaml"),
    };

    public override IReadOnlyList<OpenApiDocumentPart> LoadPartials() => new[]
    {
        Load("users",    "openapi/users/openapi.yaml"),
        Load("products", "openapi/products/openapi.json"),
    };
}

2. Merger (optional)

public class MyOpenApiDocumentMerger : OpenApiDocumentMerger
{
    protected override string GetServerUrl()
        => Environment.GetEnvironmentVariable("ENVIRONMENT") switch
        {
            "prd" => "https://api.swepay.com.br",
            "hml" => "https://sandbox.api.swepay.com.br",
            _     => "https://localhost:5001"
        };

    protected override string GetApiTitle()       => "Swepay API";
    protected override string GetApiDescription() => "Consolidated OpenAPI spec for partner integrations.";
}

3. Provider

var reader   = new OpenApiResourceReader(typeof(Program).Assembly, "MyApp.");
var loader   = new MyOpenApiDocumentLoader(reader);
var merger   = new MyOpenApiDocumentMerger();
var linter   = new OpenApiLinter(OpenApiLintOptions.Empty);
var provider = new OpenApiDocumentProvider(loader, merger, linter);

provider.WarmUp();

var json = provider.Document.Json;
var yaml = provider.Document.Yaml;

Linting

var options = new OpenApiLintOptions(
    RequiredErrorResponses: ["400", "401", "500"],
    SensitiveFieldNames:    ["password", "token", "secret"],
    DisallowedGenericSegments: ["data", "items"]);

var linter = new OpenApiLinter(options);

Checks:

• OpenAPI version is 3.1.0
• Every path is versioned (e.g. /v1/)
• Every operation has a security block (or explicit security: [] for anonymous)
• Required error responses are declared
• Sensitive fields carry a description

[ApiResponse] on handler methods (v1.6.0+)

Co-locate per-status responses with the handler:

using Native.OpenApi;
using NativeMediator;

public class GetProductHandler : IRequestHandler<GetProductCommand, GetProductResponse>
{
    [ApiResponse(200, typeof(GetProductResponse))]
    [ApiResponse(404, typeof(ErrorResponse))]
    [ApiResponse(400, typeof(ProblemDetails), "application/problem+json")]
    [ApiResponse(422, null,                  "application/problem+json")]   // → SwepayProblemDetails (F13)
    public ValueTask<GetProductResponse> Handle(GetProductCommand r, CancellationToken ct) { ... }
}

Native AOT

<PropertyGroup>
  <PublishAot>true</PublishAot>
  <IsAotCompatible>true</IsAotCompatible>
  <IsTrimmable>true</IsTrimmable>
</PropertyGroup>

All JSON/YAML serialization flows through source-generated JsonSerializerContext. No runtime reflection on consumer types.

Related

• NativeLambdaRouter.SourceGenerator.OpenApi — Roslyn generator that reads the attributes above
• Root repository · Changelog · UX RFC

License

MIT