Kanject.Core.Api.Annotations 1.8.0

Kanject.Core.Api.Annotations

Kanject.Core.Api.Annotations is a Roslyn source generator plus analyzers for ASP.NET Core minimal APIs. You write endpoints as public static methods on a static class marked [ApiEndpoints]; at compile time it generates the MapGroup / MapGet / MapPost … registration code, carries your XML doc comments into OpenAPI summaries and descriptions, and writes a Markdown catalog of every route on each build.

Analyzers catch the mistakes that would otherwise make the generator skip an endpoint without telling you — a non-static class, a private method, duplicate routes — and four of them come with code fixes.

Installation

dotnet add package Kanject.Core.Api.Abstractions
dotnet add package Kanject.Core.Api.Annotations

<ItemGroup>
  <PackageReference Include="Kanject.Core.Api.Abstractions" />                   
  <PackageReference Include="Kanject.Core.Api.Annotations" PrivateAssets="all" /> 
</ItemGroup>

This package is not marked as a development dependency, so dotnet add package writes a plain reference without PrivateAssets or IncludeAssets. Add PrivateAssets="all" yourself so the generator and its build targets stay in your project instead of flowing to projects that reference it.

The attribute types live in Kanject.Core.Api.Abstractions (there is no separate .Attributes package). Kanject.Core.Api and Kanject.Core.ApiV2 both bring that package in, but neither references this generator — add it explicitly wherever you declare [ApiEndpoints] classes. It depends on Kanject.Core.Annotations, which NuGet restores automatically.

The analyzer assembly targets netstandard2.0. Use it in ASP.NET Core projects on .NET 8, .NET 9 or .NET 10: the attribute types come from Kanject.Core.Api.Abstractions (net8.0–net10.0), and the generated code uses minimal-API route groups.

Quick start

using Kanject.Core.Api.Abstractions.Attributes;
using Microsoft.AspNetCore.Authorization;

namespace Contoso.Orders.Endpoints;

/// <summary>Order management endpoints.</summary>
[ApiEndpoints("Orders", "api/orders")]
public static class OrderEndpoints
{
    /// <summary>Lists the caller's orders.</summary>
    [HttpGet]
    public static async Task<IResult> ListOrders(IOrderStore store, CancellationToken ct)
        => Results.Ok(await store.ListAsync(ct));

    /// <summary>Returns one order.</summary>
    /// <remarks>Responds 404 when the order does not exist.</remarks>
    [HttpGet("{id:guid}")]
    public static async Task<IResult> GetOrder(Guid id, IOrderStore store, CancellationToken ct)
        => await store.FindAsync(id, ct) is { } order ? Results.Ok(order) : Results.NotFound();

    /// <summary>Liveness probe for the orders group.</summary>
    [AllowAnonymous]
    [HttpGet("ping")]
    public static IResult PingOrders() => Results.Ok();
}

using Contoso.Orders.Endpoints;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAuthentication(/* your scheme */);
builder.Services.AddAuthorization();
builder.Services.AddScoped<IOrderStore, OrderStore>();

var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();

app.MapKanjectEndpoints();   // every [ApiEndpoints] class in this project

app.Run();

Enable XML documentation in the project so the compiler parses your doc comments — the generator reads <summary> and <remarks> from them, and without it KANAPI011 reports every endpoint as undocumented:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

What gets generated

For each [ApiEndpoints] class, in the class's namespace (abridged):

public sealed class OrderEndpointsEndpointOptions
{
    public Action<RouteHandlerBuilder>? ListOrders { get; set; }
    public Action<RouteHandlerBuilder>? GetOrder { get; set; }
    public Action<RouteHandlerBuilder>? PingOrders { get; set; }
}

public static class OrderEndpointsRouteRegistration
{
    public static IEndpointRouteBuilder MapOrderEndpoints(this IEndpointRouteBuilder app,
        Action<RouteGroupBuilder>? configureGroup = null,
        Action<OrderEndpointsEndpointOptions>? configureEndpoints = null)
    {
        var group = app.MapGroup("api/orders")
            .WithTags("Orders")
            .RequireAuthorization()
            .WithDescription("Order management endpoints.");
        configureGroup?.Invoke(group);
        // ...
        var endpointGetOrder = group.MapGet("{id:guid}", OrderEndpoints.GetOrder)
            .WithName(nameof(OrderEndpoints.GetOrder))
            .WithSummary("Returns one order.")
            .WithDescription("Responds 404 when the order does not exist.");
        endpointOptions.GetOrder?.Invoke(endpointGetOrder);
        // ...
        return app;
    }
}

Plus one KanjectEndpointRegistration.MapKanjectEndpoints() that calls every group's Map{ClassName}(). It is generated into the shortest namespace among your endpoint classes, so import that namespace where you call it.

Groups, routes and authorization

[ApiEndpoints] takes the OpenAPI tag and the route prefix positionally, or as named properties:

Verb attributes take an optional route template relative to the group ([HttpGet("{id:guid}")]); no template maps the group root. Per method, use ASP.NET Core's own attributes from Microsoft.AspNetCore.Authorization: [AllowAnonymous] opts the endpoint out of the group requirement, and [Authorize(Policy = "...")] or [Authorize(Roles = "...")] adds a requirement. The generator mirrors them as AllowAnonymous() / RequireAuthorization(...) calls on the endpoint.

Configuring groups and endpoints

Call the per-group method instead of MapKanjectEndpoints() when a group needs extra conventions:

app.MapOrderEndpoints(
    configureGroup: group => group.RequireCors("frontend"),
    configureEndpoints: endpoints =>
    {
        endpoints.PingOrders = endpoint => endpoint.ExcludeFromDescription();
    });

MapKanjectEndpoints() maps every group with no callbacks. Don't call it and a per-group Map…() for the same class, or the routes are registered twice.

Rules and gotchas

• The class must be static (KANAPI001) and endpoint methods public static (KANAPI002); anything else is skipped by the generator.
• Each endpoint is named after its method (WithName(nameof(...))). ASP.NET Core requires endpoint names to be unique, and OpenAPI tools use them as operation IDs, so keep method names unique across all [ApiEndpoints] classes — ListOrders, not List.
• Only the first verb attribute on a method is used (KANAPI013).
• Return IResult or a concrete type; MVC's IActionResult belongs to controllers (KANAPI007), and void / Task give an implicit empty 200 (KANAPI008).
• The Kanject verb attributes share their names with Microsoft.AspNetCore.Mvc.HttpGetAttribute and friends. If an endpoint file also imports Microsoft.AspNetCore.Mvc (for [FromBody], [FromServices], …), [HttpGet] becomes ambiguous — alias or fully qualify one of them.

API schema document

After each build the package's MSBuild targets write <AssemblyName>.apischema.md next to the project file: a Markdown catalog with an overview, endpoint groups, a route map, an authorization matrix, OpenAPI documentation coverage and registration snippets. It is useful as reference documentation and as context for AI coding assistants.

To extract the document, the targets set EmitCompilerGeneratedFiles to true when GenerateApiSchema is on and you haven't set it yourself, so generated sources are also written under obj/. The generator additionally embeds the same Markdown in your compiled assembly as [assembly: AssemblyMetadata("ApiSchema", ...)]; GenerateApiSchema=false does not remove that attribute.

Diagnostics

Related packages

License

Licensed under the Kanject Code Libraries License Agreement (KCLLA); the full text ships in this package as LICENSE.md. Organizations whose trailing-twelve-month gross revenue and total funding raised are each below US$250,000 may use it at no cost under the Free Tier. At or above either threshold a commercial license is required — contact commercial@kanjectbusiness.com.