TerraScale.MinimalEndpoints 1.0.7

TerraScale.MinimalEndpoints

A source generator library that makes it easier to work with Minimal APIs in ASP.NET Core by providing a per-endpoint file pattern with automatic registration.

Features

• Per-endpoint file pattern: Enforces the Single Responsibility Principle by requiring one endpoint per file.
• Automatic registration: Endpoints are automatically discovered and registered.
• Class-level HTTP method attributes: Use [HttpGet], [HttpPost], [HttpPut], [HttpDelete], [HttpPatch] attributes on the class.
• Endpoint Groups: Organize endpoints into groups with shared prefixes and configuration.
• Dependency injection support: Use [FromServices] attribute to inject services.
• Parameter binding: Support for [FromBody], [FromRoute], [FromQuery], [FromHeader], [FromForm] attributes.
• Source generation: Compile-time generation with no runtime overhead.
• OpenAPI support: Built-in support for OpenAPI metadata including Tags, Summaries, Descriptions, Produces, and Consumes.
• Advanced features: Rate limiting, output caching, CORS, request timeouts, antiforgery, and more.

Usage

1. Define an endpoint group

Endpoint groups define a common prefix and configuration for a set of endpoints.

using TerraScale.MinimalEndpoints.Groups;

public class UserManagementGroup : EndpointGroup
{
    public override string Name => "User Management";
    public override string RoutePrefix => "/api/users";
    
    public override void Configure(RouteGroupBuilder builder)
    {
        builder.WithTags("Users");
    }
}

2. Define an endpoint class

Each endpoint class must implement IMinimalEndpoint or inherit from BaseMinimalApiEndpoint<TGroup>. Place HTTP method and route attributes on the class, and implement a HandleAsync method.

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using TerraScale.MinimalEndpoints;
using TerraScale.MinimalEndpoints.Attributes;

/// <summary>
/// Creates a new user.
/// </summary>
[HttpPost("")]  // Route combines with group prefix: /api/users
[Authorize(Roles = "Admin")]
[Consumes("application/json")]
[Produces("application/json")]
public class CreateUserEndpoint : BaseMinimalApiEndpoint<UserManagementGroup>
{
    public async Task<IResult> HandleAsync(
        [FromBody] CreateUserRequest request, 
        [FromServices] IUserService userService)
    {
        var user = await userService.CreateAsync(request);
        return Results.Ok(user);
    }
}

3. Register endpoints in Program.cs

Use the generated extension methods to register services and map endpoints. The namespace will be TerraScale.MinimalEndpoints.Generated_{AssemblyName} (replacing non-alphanumeric characters with underscores).

using TerraScale.MinimalEndpoints.Generated_YourAssembly_Name;

var builder = WebApplication.CreateBuilder(args);

// Add application services
builder.Services.AddScoped<IUserService, UserService>();

// Register Minimal Endpoints services (automatically registers all endpoint classes)
builder.Services.AddGeneratedMinimalEndpoints();

var app = builder.Build();

// Map Minimal Endpoints routes
app.MapGeneratedMinimalEndpoints();

app.Run();

Attributes

Class-Level HTTP Method Attributes

• [HttpGet(route)] - HTTP GET method
• [HttpPost(route)] - HTTP POST method
• [HttpPut(route)] - HTTP PUT method
• [HttpDelete(route)] - HTTP DELETE method
• [HttpPatch(route)] - HTTP PATCH method
• [HttpHead(route)] - HTTP HEAD method
• [HttpOptions(route)] - HTTP OPTIONS method

OpenAPI Attributes

• [EndpointGroupName(name)] - Specifies the group name for OpenAPI documentation
• [Produces(contentType)] - Specifies the response content type
• [Consumes(contentType)] - Specifies the request content type
• [ProducesResponseType(type, statusCode)] - Specifies a response type
• [ProducesProblem(statusCode)] - Documents a problem details response
• [ProducesValidationProblem] - Documents a validation problem response

Advanced Feature Attributes

• [RateLimiting(policy)] / [DisableRateLimiting] - Rate limiting configuration
• [OutputCache(duration)] - Output caching configuration
• [EnableCors(policy)] / [DisableCors] - CORS policy configuration
• [RequestTimeout(milliseconds)] / [DisableRequestTimeout] - Request timeout configuration
• [DisableAntiforgery] / [RequireAntiforgery] - Antiforgery configuration
• [EndpointFilter(type)] - Apply endpoint filters

Standard Attributes

• [FromServices], [FromBody], [FromRoute], [FromQuery], [FromHeader], [FromForm]
• [Authorize], [AllowAnonymous]

Base Class & Interface

BaseMinimalApiEndpoint<TGroup>

A convenience base class that implements IMinimalEndpoint and is associated with an endpoint group. It provides helper methods like Ok(), NotFound(), BadRequest(), etc.

public abstract class BaseMinimalApiEndpoint<TGroup> : BaseMinimalApiEndpoint 
    where TGroup : class, IEndpointGroup, new()
{
    public Type? GroupType => typeof(TGroup);
}

BaseMinimalApiEndpoint

The non-generic base class for endpoints that don't belong to a group.

IMinimalEndpoint

The interface that all endpoint classes must implement.

public interface IMinimalEndpoint
{
    string? GroupName { get; }
    string[]? Tags { get; }
}

EndpointGroup

The base class for defining endpoint groups.

public abstract class EndpointGroup : IEndpointGroup
{
    public abstract string Name { get; }
    public abstract string RoutePrefix { get; }
    public abstract void Configure(RouteGroupBuilder builder);
}

Generated Code

The source generator automatically creates a MinimalEndpointRegistration class with:

• AddGeneratedMinimalEndpoints(): Registers all endpoint classes in DI.
• MapGeneratedMinimalEndpoints(): Maps all endpoints to routes.

The generated code handles:

• Service resolution
• Parameter binding
• OpenAPI metadata generation (Tags, Summary, Description, Produces/Accepts)
• Authentication/Authorization metadata
• Rate limiting, output caching, CORS, request timeouts

Best Practices

• One Endpoint Per File: The library enforces this pattern. Split your endpoints (Get, Post, Put, Delete) into separate classes.
• Use Endpoint Groups: Organize related endpoints into groups with shared configuration.
• Use BaseMinimalApiEndpoint<TGroup>: Inherit from this class to associate endpoints with groups.
• Use XML Documentation: The generator automatically extracts <summary>, <remarks>, <response>, and <param> tags from XML documentation to populate OpenAPI descriptions.
• Configure Method: Use the static Configure method on endpoint classes for custom endpoint configuration.

Example

using TerraScale.MinimalEndpoints;
using TerraScale.MinimalEndpoints.Attributes;

/// <summary>
/// Gets weather information for a city.
/// </summary>
/// <response code="200">Returns weather data</response>
/// <response code="400">Invalid city parameter</response>
[HttpGet("")]
[Produces("application/json")]
public class GetWeatherEndpoint : BaseMinimalApiEndpoint<WeatherGroup>
{
    public async Task<IResult> HandleAsync([FromQuery] string? city)
    {
        var weather = await GetWeatherAsync(city ?? "Unknown");
        return Results.Ok(weather);
    }
    
    // Optional: Add custom configuration
    public static void Configure(RouteHandlerBuilder builder)
    {
        builder.AddEndpointFilter<MyCustomFilter>();
    }
}