NativeLambdaRouter.SourceGenerator.OpenApi 1.8.3

NativeLambdaRouter.SourceGenerator.OpenApi

Roslyn Source Generator that emits OpenAPI 3.1 YAML at compile time from NativeLambdaRouter endpoint maps — zero runtime overhead, zero reflection.

• Version: 1.8.3
• Target: netstandard2.0 (analyzer), consumed by net10.0 projects
• Generated artifact: {OpenApiSpecName ?? AssemblyName}.Generated.GeneratedOpenApiSpec
• Interface: implements Native.OpenApi.IGeneratedOpenApiSpec when that package is referenced

Agent quick-reference

What the generator inspects

The generator walks the syntax + semantic model of each compilation looking for:

What it emits

• {assembly}.Generated.GeneratedOpenApiSpec singleton (public static readonly Instance) with:
  • YamlContent — full OpenAPI 3.1 YAML
  • EndpointCount — count of discovered endpoints (public + hidden)
  • EndpointList — (Method, Path)[] of discovered endpoints
• YAML components.schemas.SwepayProblemDetails whenever any operation serves application/problem+json without a typed body (F13)
• Per-operation Wave 1 extensions (F03 deprecation fields, F09 examples map, F12 x-swepay-errors slice) plus the root x-swepay-error-catalog
• v1.8.0 additions:
  • Root: tags (with description, x-displayName, externalDocs), x-tagGroups, externalDocs, rich info, servers, webhooks
  • Per-operation: externalDocs, x-codeSamples, x-badges, x-scalar-stability, parameters (query + header), callbacks, links under response headers, headers under responses
  • Per-schema: property description/example/default/constraints, x-order, x-additionalPropertiesName, x-enum-descriptions, x-enum-varnames
  • Polymorphism: oneOf + discriminator + mapping on base schemas; allOf on subtypes via a synthetic {Base}__Core schema
  • components/responses (BadRequest, Unauthorized, InternalServerError) and components/securitySchemes (JwtBearer) now always emitted when referenced
  • All webhook/callback payload types fully resolved in components/schemas
  • All collections deterministically sorted

Precedence rule

Fluent chain wins over command attributes when both are present — matches ASP.NET Core Minimal APIs.

Installation

<ItemGroup>
  <PackageReference Include="NativeLambdaRouter.SourceGenerator.OpenApi"
                    Version="1.8.3"
                    OutputItemType="Analyzer"
                    ReferenceOutputAssembly="false" />
  
  <PackageReference Include="NativeOpenApi" Version="1.8.3" />
</ItemGroup>

The generator is a build-time-only analyzer. ReferenceOutputAssembly="false" prevents the analyzer DLL from being published with the Lambda binary.

Supported map methods

Path parameters ({id}) are extracted into parameters: [{ in: path, required: true, schema: { type: string } }].

Wave 1 (v1.7.0) — UX attributes

Full reference: ../Native.OpenApi/README.md · Root: ../../README.md

v1.8.0 — OpenAPI 3.1 documentation features

All additions are opt-in. Scalar is the reference UI (Scalar-first policy); x-scalar-* and x-enum-* extensions are not dual-emitted for Redoc.

Assembly-level (document scope)

Command-type scope (via ApplyCommandAttributes)

Property/field scope (via TypePropertyExtractor)

Bug fixes that affect emitted YAML (v1.8.0)

Fluent metadata — pre-Wave-1 reference

routes.MapGet<GetClientsCommand, GetClientsResponse>("/v1/clients", ctx => new GetClientsCommand())
    .WithName("ListAllClients")
    .WithSummary("Retrieve all clients")
    .WithDescription("Returns a paginated list of registered clients.")
    .WithTags("Clients", "Admin")
    .ProducesProblem(422);

Attribute-based metadata on TCommand

using NativeLambdaRouter.OpenApi.Attributes;
using Native.OpenApi.Attributes;

[EndpointName("ListAllClients")]
[EndpointSummary("Retrieve all clients")]
[EndpointDescription("Returns a paginated list of registered clients.")]
[Tags("Clients", "Admin")]
[Deprecated(sunset: "2026-12-31", alternative: "GET /v2/clients", reason: "no pagination.")]
[ErrorCatalog(typeof(SwepayErrors))]
[ApiExample("happy-path", "First page of clients",
    RequestJson = "examples/list-clients/happy.json",
    ResponseStatus = 200,
    ResponseJson = "examples/list-clients/happy-response.json")]
public sealed record GetClientsCommand;

[ApiResponse] on handlers (v1.6.0+)

using Native.OpenApi;

public class CreateOrderHandler : IRequestHandler<CreateOrderCommand, CreateOrderResponse>
{
    [ApiResponse(201, typeof(CreateOrderResponse))]
    [ApiResponse(400, typeof(ValidationProblem), "application/problem+json")]
    [ApiResponse(422, null,                      "application/problem+json")]   // → SwepayProblemDetails
    [ApiResponse(500, typeof(ProblemDetails),    "application/problem+json")]
    public async ValueTask<CreateOrderResponse> Handle(CreateOrderCommand r, CancellationToken ct) { ... }
}

The generator discovers IRequestHandler<TCommand, TResponse> via the semantic model and merges the handler's [ApiResponse] list with the fluent-chain .ProducesProblem(...) responses. When a problem+json response overlaps the default 400/401/500 responses, the declared one replaces the default $ref.

Form-encoded bodies (v1.5.1+)

[Accepts("application/x-www-form-urlencoded")]
public sealed record RefreshTokenCommand(string RealmId, string ClientId, string RefreshToken, string? Scope);

Or via fluent:

routes.MapPost<RefreshTokenCommand, TokenResponse>("/v1/realms/{realm}/protocol/openid-connect/refresh", ...)
    .Accepts("application/x-www-form-urlencoded");

The generator emits an inline schema (all fields type: string, nullables excluded from required) instead of a $ref — matches the OAuth2 token endpoint convention.

Schema introspection

MSBuild properties

Shipped via build/NativeLambdaRouter.SourceGenerator.OpenApi.props (auto-imported when the package is added as a NuGet dependency).

Using ProjectReference instead of NuGet? .props is not auto-imported. Add a Directory.Build.props with the same <CompilerVisibleProperty Include="..." /> items. See samples/MultiLambdaSample/Directory.Build.props.

AWS Lambda AssemblyName=bootstrap recipe

Multiple Lambda projects with AssemblyName=bootstrap collide on the default bootstrap.Generated namespace. Override per producer:

<PropertyGroup>
  <AssemblyName>bootstrap</AssemblyName>
  <OpenApiSpecName>Swepay.Functions.Admin</OpenApiSpecName>
  <OpenApiSpecTitle>Admin API</OpenApiSpecTitle>
</PropertyGroup>

Accessing the generated spec

using MyProject.Generated;

string yaml = GeneratedOpenApiSpec.YamlContent;
int    n    = GeneratedOpenApiSpec.EndpointCount;

foreach (var (method, path) in GeneratedOpenApiSpec.EndpointList)
    Console.WriteLine($"{method} {path}");

// Polymorphic — requires the NativeOpenApi package
Native.OpenApi.IGeneratedOpenApiSpec spec = GeneratedOpenApiSpec.Instance;

EndpointList exposes all discovered endpoints, including those hidden by [HideFromDocs] / .ExcludeFromDocs(). Hidden endpoints are only absent from the YAML — runtime router wiring still sees them.

Multi-project architecture

Each producer project gets its own GeneratedOpenApiSpec under its namespace:

Functions.Admin      → Functions.Admin.Generated.GeneratedOpenApiSpec
Functions.Identity   → Functions.Identity.Generated.GeneratedOpenApiSpec
Functions.OpenId     → Functions.OpenId.Generated.GeneratedOpenApiSpec

A consolidator project merges them with NativeOpenApi:

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

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

    public override IReadOnlyList<OpenApiDocumentPart> LoadPartials() => new[]
    {
        LoadFromGeneratedSpec("admin",    Functions.Admin.Generated.GeneratedOpenApiSpec.Instance),
        LoadFromGeneratedSpec("identity", Functions.Identity.Generated.GeneratedOpenApiSpec.Instance),
        LoadFromGeneratedSpec("openid",   Functions.OpenId.Generated.GeneratedOpenApiSpec.Instance),
    };
}

Full working example: samples/MultiLambdaSample.

Debug: write generated .cs files to disk

<PropertyGroup>
  <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
</PropertyGroup>

Output path:

obj/{Configuration}/{TargetFramework}/generated/NativeLambdaRouter.SourceGenerator.OpenApi/
    NativeLambdaRouter.SourceGenerator.OpenApi.OpenApiSourceGenerator/
        GeneratedOpenApiSpec.g.cs

Not required for the generator to work — the generated class is injected directly into the compilation. EmitCompilerGeneratedFiles only produces a physical copy for inspection.

Related

• NativeOpenApi — library + renderer + attributes
• Repository root · Changelog · UX RFC

License

MIT