MinimalApiGen 1.0.0

MinimalApiGen

Compile-time Roslyn source generator that auto-registers ASP.NET Core Minimal API endpoints. Zero reflection · Native AOT safe · No runtime dependency.

Decorate a plain static class with [RouteGroup] and [Get]/[Post]/[Put]/[Patch]/[Delete], and MinimalApiGen emits a single MapGeneratedEndpoints() extension method at build time — replacing hand-written app.MapGet(...) boilerplate with one line in Program.cs. Route-parameter mismatches and non-static handlers are caught as compiler errors, not runtime 404s.

Supported .NET versions

The package targets netstandard2.0 for both the attributes and the generator, so it works unmodified on any current or future .NET version that implements netstandard2.0 — .NET 8, 9, and 10 are the versions actively built and tested in this repository's CI and sample app (samples/MinimalApiGen.Sample multi-targets all three). The generator itself is a build-time-only component (analyzers/dotnet/cs), so it never affects your app's target framework or its Native AOT / trimming compatibility.

Installation

dotnet add package MinimalApiGen

This single package brings in everything you need:

• The [RouteGroup]/[Get]/[Post]/… attribute types, added as a normal reference.
• The source generator itself, wired in automatically as a Roslyn analyzer — no other setup, no <Analyzer> entries, nothing to add to Program.cs besides the one line shown below.

How to use it — step by step

1. Install the package in your ASP.NET Core project (see above).

2. Create an endpoint class. Use a static class, tag it with [RouteGroup("/prefix")], and tag each handler method with an HTTP-verb attribute. Handler methods must be static:

   // Endpoints/ProductEndpoints.cs
   using MinimalApiGen;
   
   [RouteGroup("/api/products")]
   public static class ProductEndpoints
   {
       [Get("")]
       [EndpointMeta("List all products")]
       public static IResult GetAll(ProductService svc) =>
           Results.Ok(svc.GetAll());
   
       [Get("{id:int}")]
       public static IResult GetById(int id, ProductService svc) =>
           svc.GetById(id) is { } p ? Results.Ok(p) : Results.NotFound();
   
       [Post("")]
       [AuthorizeEndpoint("Admin")]
       public static IResult Create(CreateProductRequest req, ProductService svc)
       {
           var product = svc.Create(req);
           return Results.Created($"/api/products/{product.Id}", product);
       }
   }
   

3. Build the project. The generator runs automatically on every build — there's no extra step. If a route template references a parameter your method doesn't declare (e.g. [Get("{id:int}")] on a method with no id parameter), the build fails immediately with a MAG001 compiler error instead of surfacing as a runtime 404 later.

4. Register everything with one line in Program.cs:

   using MinimalApiGen.Generated;
   
   var builder = WebApplication.CreateBuilder(args);
   builder.Services.AddSingleton<ProductService>();
   builder.Services.AddAuthorization();
   
   var app = builder.Build();
   app.UseAuthorization();
   
   app.MapGeneratedEndpoints();   // ← every [RouteGroup]-decorated class, one line
   app.Run();
   

5. Run your app as normal (dotnet run). Every endpoint from every [RouteGroup] class in your project is registered — add a new endpoint method any time and it's picked up on the next build, with no change needed to Program.cs.

6. (Optional) Exclude an endpoint from generation with [ExcludeFromGeneration] and map it yourself, for handlers too complex for attribute declaration:

   [ExcludeFromGeneration]
   public static IResult Search(string q, ProductService svc) => /* ... */;
   
   // Program.cs, after MapGeneratedEndpoints():
   app.MapGet("/api/products/search", ProductEndpoints.Search);
   

See samples/MinimalApiGen.Sample in the source repository for a complete, runnable ASP.NET Core project using every attribute below, including versioned endpoints and route groups for two separate resources.

Attributes

Diagnostics

Versioning

This package follows Semantic Versioning 2.0:

• MAJOR — breaking attribute/API changes, or a change to the shape of generated code that requires consumer changes (e.g. renaming MapGeneratedEndpoints).
• MINOR — new attributes, new diagnostics, or new optional behavior that doesn't break existing consumers.
• PATCH — generator/diagnostic bug fixes with no API surface change.

See the package's release notes on NuGet (or PackageReleaseNotes in src/MinimalApiGen/MinimalApiGen.csproj) for the changelog of each published version.