ErrorApi.Abstractions 1.0.1

A Roslyn source generator that turns a Result<T> error catalog into a Minimal API error mapper and an OpenAPI document that actually lists the failures — plus a TypeScript union for the client.

Result libraries fixed the return type. They did not fix the contract: ErrorOr, FluentResults and friends map a failure to ProblemDetails at runtime, so the OpenAPI document still says 200 OK and nothing else. The frontend has no idea a 409 Orders.AlreadyPaid exists until it happens in production.

ErrorApi resolves that at compile time — and it does so whether you use its own Result<T>, ErrorOr, OneOf, language-ext, a hand-rolled discriminated union, or no result type at all: plain exceptions work too.

What it looks like

Swagger UI, POST /orders/{id}/pay — five responses, each carrying its own codes, titles and example bodies. Note the 422: two different failures share one status, and each keeps its own code.

dotnet run --project samples/Sample.Api

http://localhost:5080/swagger · /scalar · /openapi/v1.json · /openapi/errors.ts — and the same API is built once per declaration style under samples/, each with its own README, all producing the identical contract.

First steps

One package is the whole install — it brings the generator, the primitives and the ASP.NET Core integration (and the Swashbuckle filter on .NET 8/9):

dotnet add package ErrorApi

1. Declare the catalog — the class declares membership and the default status, the members declare the names; nothing else needs typing:

[ErrorCatalog("Orders", StatusCodes.Status404NotFound)]
public static partial class OrderErrors
{
    public static partial Error NotFound { get; }                              // Orders.NotFound, 404

    [Error(StatusCodes.Status409Conflict, Detail = "Order {0} was already paid.")]
    public static partial Error AlreadyPaid(Guid orderId);                     // Orders.AlreadyPaid, 409
}

2. Return the entries — Error converts implicitly into Result<T>:

public Result<Order> GetById(Guid id) =>
    _orders.TryGetValue(id, out var order) ? order : OrderErrors.NotFound;

3. Wire it up once — AddErrorApi() is the whole minimal setup, and every knob is a lambda on it:

builder.Services.AddOpenApi();
builder.Services.AddErrorApi();          // or AddErrorApi(x => x.AddExceptionHandler().Include(...))

app.MapGet("/orders/{id:guid}", (Guid id, IOrderService s) => s.GetById(id).ToHttpResult());

On .NET 8/9 the document comes through Swagger — the ErrorApi package already carries the filter, so services.AddSwaggerGen(c => c.AddErrorApiResponses()); replaces AddOpenApi() and that is all. A .NET 10 project that stays on Swagger adds ErrorApi.Swashbuckle for the identical responses, built by the same shared code.

Already on ErrorOr, OneOf, language-ext, FluentResults, Ardalis.Result or CSharpFunctionalExtensions? Take the matching adapter package and keep your types — often a bare [Error] on what you already wrote is the entire onboarding. See docs/adapters.md and docs/getting-started.md.

How it works

1. The generator reads your [Error]/[ErrorCatalog] declarations into a catalog — codes, statuses and titles inferred from what is already written (names, bodies, base constructors).
2. It finds every endpoint — Minimal API Map* call sites and attribute-routed controllers — and walks each handler through the call graph: into interfaces and their implementations, past mediators via the message type, into pipeline behaviours, and across assembly boundaries through baked-in exports.
3. What it cannot see, it says out loud: thirteen EAPI diagnostics report stopped walks, drifting codes and unreachable entries at build time, instead of letting the contract lie.
4. It emits a reflection-free model — switch statements, no runtime scan — that one OpenAPI transformer (or the Swashbuckle filter) and a TypeScript writer render from.
5. At runtime the same model maps every failure to application/problem+json carrying a stable code member, so the response always matches the document.

The full mechanics: docs/discovery.md · docs/catalog.md · docs/typescript.md.

Why it is worth it

• The contract stops lying. Every reachable failure is documented per endpoint, and the response body always matches — same model on both sides.
• Nothing is written twice. Codes come from names or bodies, statuses from catalogs or base constructors; duplication is what the diagnostics hunt down, not what the library asks for.
• Keep your result library. Seven adapters produce byte-identical contracts; exceptions work too.
• The client gets a compiler. errors.ts turns catch folklore into an exhaustive union — add a failure server-side and the frontend build breaks instead of production.
• Free at runtime. No reflection on the request path, native-AOT clean, and measured: success costs the same as hand-written TypedResults.Ok.

ErrorOr solves the return type, NSwag solves the client shape — neither answers "which errors does this endpoint return?". ErrorApi answers exactly that question and leans on the others for the rest.

Benchmarks

BenchmarkDotNet, raw TypedResults as the floor. One machine (x64, .NET 10):

And per framework, measured together on one CI runner (Ubuntu 24.04, shared hardware — read as relative, not absolute):

The story holds on every framework the packages ship for: success at the floor's cost (the 48 B on net8 is the framework's own Ok<int> box, identical for hand-written code), lookups allocation-free. CI re-runs all three on every push and keeps the results as per-commit artifacts.

Full tables, methodology and the optimizations the first run bought: docs/performance.md · benchmarks/.

Documentation

MIT licensed.