FluentEndpoints.Generators 1.0.1

FluentEndpoints

FluentEndpoints is a small set of libraries for defining application endpoints as plain .NET types and mapping them to a transport (HTTP today) via a minimal, fluent configuration API.

The core idea:

• An endpoint is a class implementing IEndpoint<TRequest, TResponse> (or IEndpoint<TRequest> for no payload).
• Each endpoint has a static Configure(IEndpointBuilder builder) method where you map it to a transport.
• A transport-specific resolver registers endpoints into DI and maps them onto the transport runtime (ASP.NET Core routing for HTTP).
• A source generator can produce convenience extension methods to register/map all endpoints discovered at compile time.

Packages / projects

This repository contains multiple projects:

• src/FluentEndpoints.Contracts: core abstractions (IEndpointDefinition, IEndpointBuilder, resolvers).
• src/FluentEndpoints.Http: HTTP transport implementation for ASP.NET Core minimal APIs (HttpEndpointResolver, HttpEndpointOptions, mapping helpers).
• src/FluentEndpoints.Generators: Roslyn source generator that emits endpoint registration/mapping extensions.
• sample/*: sample applications (e.g. FluentEndpoints.Features.HttpService).
• tests/*: unit + generator + integration tests.

Defining an endpoint

Endpoints are plain classes.

Example (from sample/FluentEndpoints.Features.HttpService):

• The endpoint class implements IEndpoint<TRequest, TResponse>.
• Configure maps the endpoint to HTTP using MapGet.

record GetUserRequest(int Id);

record User(int Id, string Name);

class GetUser : IEndpoint<GetUserRequest, Results<Ok<User>, NotFound>>
{
    public static void Configure(IEndpointBuilder builder)
        => builder.MapGet("/users/{id:int}");

    public async Task<Results<Ok<User>, NotFound>> Handle(
        GetUserRequest request,
        CancellationToken cancellationToken)
    {
        return request.Id == 1
            ? TypedResults.Ok(new User(1, "Alice"))
            : TypedResults.NotFound();
    }
}

HTTP mapping API

FluentEndpoints.Http provides convenience methods on IEndpointBuilder:

• MapGet(pattern)
• MapPost(pattern)
• MapPut(pattern)
• MapDelete(pattern)
• MapPatch(pattern)
• Map(method, pattern)

These return HttpEndpointOptions so you can attach HTTP-specific configuration (metadata/conventions) before the endpoint is mapped.

Registering and mapping endpoints (HTTP)

The HTTP transport uses HttpEndpointResolver:

• AddEndpoint<TEndpoint, TRequest, TResponse>(IServiceCollection) registers the endpoint type into DI.
• MapEndpoint<TEndpoint, TRequest, TResponse>(IEndpointRouteBuilder, IServiceScope) maps it onto ASP.NET Core routing based on what Configure produced.

In the sample app, the recommended way is to use the generated extension methods (see next section) rather than mapping endpoints one-by-one.

Source generator

FluentEndpoints.Generators scans the compilation for implementations of FluentEndpoints.IEndpointDefinition<,> and emits extension methods to:

• register endpoints into DI, and
• map endpoints onto an IEndpointRouteBuilder.

Generated files include:

• ServiceCollection.Extensions.g.cs
• EndpointRouteBuilder.Extensions.g.cs

This enables a “register/map all endpoints” workflow without manual wiring.

Status

This repository is an initial implementation. APIs may change as transports and endpoint conventions evolve.