Moclawr.MinimalAPI 2.1.9

Moclawr.MinimalAPI

Overview

Moclawr.MinimalAPI provides a class-based approach to ASP.NET Core Minimal APIs with automatic endpoint discovery, MediatR integration, and enhanced OpenAPI documentation. It bridges the gap between minimal APIs and traditional controller-based APIs by offering a structured, object-oriented approach while maintaining the performance benefits of minimal APIs.

Key Features

• Class-Based Endpoints: Object-oriented endpoint design with base classes (SingleEndpointBase, CollectionEndpointBase)
• Automatic Discovery: Auto-registration of endpoint classes from assemblies via reflection
• MediatR Integration: Built-in CQRS pattern support with ICommand<T> and IQueryRequest<T> interfaces
• Advanced API Versioning: Multiple versioning strategies (URL segment, query string, headers)
• Enhanced OpenAPI Documentation: Rich SwaggerUI with automatic schema generation and versioned documents
• Dynamic Feature Tagging: Completely dynamic endpoint grouping based on actual namespace structure
• Unique Operation IDs: Deterministic hash-based operation IDs prevent duplicate endpoint names
• Intelligent Request Binding: Automatic parameter binding from route, query, body, form, and headers with attributes
• Type-Safe Endpoints: Strongly-typed request and response handling with generic base classes
• Flexible Response Types: Support for Response<T>, ResponseCollection<T>, and custom response wrappers
• Attribute-Based Configuration: Declarative endpoint configuration with comprehensive OpenAPI attributes
• File Upload Support: Built-in support for IFormFile and multi-file uploads

Latest Updates (v2.1.2)

• ✅ Complete Dynamic Discovery: No hardcoded feature names - adapts to any namespace structure
• ✅ Enhanced Route Matching: Improved endpoint-to-operation matching with normalized route patterns
• ✅ Deterministic Operation IDs: Hash-based unique identifiers with readable prefixes
• ✅ Advanced Parameter Binding: Smart binding with FromRoute, FromQuery, FromBody, FromForm, FromHeader attributes
• ✅ Comprehensive OpenAPI Support: Full attribute system for documentation and parameter specification

Installation

Install the package via NuGet Package Manager:

dotnet add package Moclawr.MinimalAPI

Quick Start

1. Register Services

In your Program.cs:

using MinimalAPI;

var builder = WebApplication.CreateBuilder(args);

// Configure enhanced versioning options
var versioningOptions = new DefaultVersioningOptions
{
    Prefix = "v",
    DefaultVersion = 1,
    SupportedVersions = [1, 2],
    IncludeVersionInRoute = true,
    BaseRouteTemplate = "/api",
    ReadingStrategy = VersionReadingStrategy.UrlSegment | VersionReadingStrategy.QueryString,
    AssumeDefaultVersionWhenUnspecified = true
};

// Add MinimalAPI with comprehensive documentation
builder.Services.AddMinimalApiWithSwaggerUI(
    title: "My API",
    version: "v1",
    description: "API built with MinimalAPI framework",
    contactName: "Development Team",
    contactEmail: "dev@company.com",
    versioningOptions: versioningOptions,
    assemblies: [typeof(Program).Assembly]
);

var app = builder.Build();

// Auto-discover and map all endpoints with versioning
app.MapMinimalEndpoints(versioningOptions, typeof(Program).Assembly);

// Enable comprehensive documentation
if (app.Environment.IsDevelopment())
{
    app.UseMinimalApiDocs(
        swaggerRoutePrefix: "docs",
        enableTryItOut: true,
        enableDeepLinking: true,
        enableFilter: true
    );
}

app.Run();

2. Create Endpoints with Full Attribute Support

using MinimalAPI.Endpoints;
using MinimalAPI.Attributes;
using MediatR;

namespace MyApp.Endpoints.Users.Commands;

[OpenApiSummary("Create user account", 
    Description = "Creates a new user with validation and notification",
    Tags = ["User Management"])]
[OpenApiParameter("sendEmail", typeof(bool), 
    Description = "Send welcome email", Location = ParameterLocation.Query)]
[OpenApiResponse(201, ResponseType = typeof(Response<UserDto>), 
    Description = "User created successfully")]
[OpenApiResponse(400, Description = "Invalid user data")]
[ApiVersion(1)]
public class CreateUserEndpoint(IMediator mediator) 
    : SingleEndpointBase<CreateUserCommand, UserDto>(mediator)
{
    [HttpPost("users")]
    public override async Task<Response<UserDto>> HandleAsync(
        CreateUserCommand request, CancellationToken ct)
    {
        return await _mediator.Send(request, ct);
    }
}

3. Advanced Request Binding with Priority Rules

The framework now follows a clear priority system for parameter binding:

Priority Order:

1. Explicit Attributes (highest priority): [FromRoute], [FromQuery], [FromHeader], [FromForm], [FromBody]
2. Type-based Detection: IFormFile types automatically use form binding
3. HTTP Method Defaults:
   • GET: Properties default to query parameters
   • POST/PUT/PATCH: Properties default to request body (JSON) unless form data is detected

using MediatR;
using MinimalAPI.Attributes;
using MinimalAPI.Handlers.Command;

// Command example - follows POST/PUT/PATCH rules
public record CreateUserCommand : ICommand<UserDto>
{
    // These will be in request body (JSON) - default for commands
    public string Name { get; init; } = string.Empty;
    public string Email { get; init; } = string.Empty;
    
    // This will be a query parameter - explicit attribute overrides default
    [FromQuery] public bool SendWelcomeEmail { get; init; } = true;
    
    // This will be from header - explicit attribute
    [FromHeader("X-Client-Version")] public string? ClientVersion { get; init; }
    
    // This will be from route parameter - explicit attribute
    [FromRoute("tenantId")] public string? TenantId { get; init; }
}

// File upload example - auto-detects form data
public record UploadFileCommand : ICommand<FileDto>
{
    // These will be form fields - explicit FromForm attributes
    [FromForm] public IFormFile File { get; init; } = default!;
    [FromForm] public string Description { get; init; } = string.Empty;
    
    // This will be a query parameter - explicit attribute
    [FromQuery] public string? Folder { get; init; }
}

// Mixed form and body example
public record UpdateProfileCommand : ICommand<UserDto>
{
    // Route parameter
    [FromRoute] public int UserId { get; init; }
    
    // Form file upload
    [FromForm] public IFormFile? Avatar { get; init; }
    
    // Form fields
    [FromForm] public string? Bio { get; init; }
    
    // JSON body properties (remaining properties without explicit attributes)
    public string Name { get; init; } = string.Empty;
    public string Email { get; init; } = string.Empty;
    
    // Query parameter
    [FromQuery] public bool NotifyFollowers { get; init; } = true;
}

// Query example - follows GET rules
public record GetUsersQuery : IQueryCollectionRequest<UserDto>
{
    // These will be query parameters automatically - default for queries
    public string? Search { get; init; }
    public int Page { get; init; } = 1;
    public int Size { get; init; } = 10;
    
    // This will be from route - explicit attribute overrides default
    [FromRoute] public string TenantId { get; init; } = string.Empty;
}

Auto-Detection Rules:

• IFormFile, IFormFile[], List<IFormFile> → Automatically treated as form data
• Properties ending with "Id" or named "id" → Prefer route parameters when no explicit attribute
• Commands (POST/PUT/PATCH) → Body parameters by default
• Queries (GET) → Query parameters by default
• Form content type detected → All non-attributed properties become form fields

Dynamic Feature Discovery

The framework automatically discovers and organizes endpoints based on your actual namespace structure:

Completely Dynamic Tagging

No hardcoded feature names - the framework adapts to any organization:

// Any namespace pattern works:
namespace MyApp.Endpoints.UserManagement.Operations    → "UserManagement Operations"
namespace CompanyApi.Endpoints.Finance.Reports        → "Finance Reports"  
namespace System.Endpoints.Authentication.Security    → "Authentication Security"
namespace Api.Endpoints.S3.Commands                   → "S3 Commands"
namespace Project.Endpoints.Analytics.Dashboards     → "Analytics Dashboards"
namespace sample.API.Endpoints.Todos.Commands         → "Todos Commands"
namespace sample.API.Endpoints.Tags.Queries           → "Tags Queries"
namespace sample.API.Endpoints.AutofacDemo.Commands   → "AutofacDemo Commands"

Explicit Tag Override

Always use explicit tags when you want specific grouping:

[OpenApiSummary("Complex operation", 
    Tags = ["Custom Category", "Special Operations"])]
public class ComplexEndpoint : SingleEndpointBase<ComplexCommand, ComplexResponse>
{
    // Explicit tags override namespace-based generation
}

Unique Operation IDs

Deterministic hash-based operation IDs ensure no conflicts:

Operation ID Format: {FeatureName}_{EndpointName}_{HttpMethod}_{Hash8}

Examples:
- Users_CreateUser_POST_a1b2c3d4
- S3_DeleteFile_DELETE_f9e8d7c6  
- Orders_UpdateStatus_PUT_3c7b8a9d
- Products_GetDetails_GET_b5f2e1a8

The 8-character hash is generated deterministically from:

• Full endpoint type name
• HTTP method
• Route template

This ensures consistent, unique identifiers across deployments.

Advanced Versioning System

Multiple Version Support

[ApiVersion(1)]
public class GetUsersV1Endpoint : CollectionEndpointBase<GetUsersQuery, UserDtoV1>
{
    [HttpGet("users")]
    public override async Task<ResponseCollection<UserDtoV1>> HandleAsync(...)
    {
        // Version 1 implementation with basic fields
    }
}

[ApiVersion(2)]
public class GetUsersV2Endpoint : CollectionEndpointBase<GetUsersQueryV2, UserDtoV2>
{
    [HttpGet("users")]
    public override async Task<ResponseCollection<UserDtoV2>> HandleAsync(...)
    {
        // Version 2 with enhanced features and additional fields
    }
}

Flexible Version Reading

The framework supports multiple versioning strategies:

var versioningOptions = new DefaultVersioningOptions
{
    ReadingStrategy = VersionReadingStrategy.UrlSegment |   // /api/v1/users
                     VersionReadingStrategy.QueryString |  // /api/users?version=1  
                     VersionReadingStrategy.Header,        // X-API-Version: 1
    
    // Route generation
    BaseRouteTemplate = "/api",
    IncludeVersionInRoute = true,
    
    // Version validation
    SupportedVersions = [1, 2, 3],
    AssumeDefaultVersionWhenUnspecified = true
};

Enhanced OpenAPI Documentation

Comprehensive Attribute System

[OpenApiSummary("Upload user profile image", 
    Description = "Uploads and processes a user profile image with validation")]
[OpenApiParameter("userId", typeof(int), 
    Description = "User identifier", Required = true, Location = ParameterLocation.Path)]
[OpenApiParameter("generateThumbnail", typeof(bool), 
    Description = "Generate thumbnail", Location = ParameterLocation.Query)]
[OpenApiResponse(200, ResponseType = typeof(Response<ImageDto>), 
    Description = "Image uploaded successfully")]
[OpenApiResponse(400, Description = "Invalid file format")]
[OpenApiResponse(413, Description = "File too large")]
[ApiVersion(1)]
public class UploadProfileImageEndpoint : SingleEndpointBase<UploadImageCommand, ImageDto>
{
    [HttpPost("users/{userId}/profile-image")]
    public override async Task<Response<ImageDto>> HandleAsync(...) => 
        await _mediator.Send(request, ct);
}

Automatic Schema Generation

The framework automatically generates OpenAPI schemas for:

• Request Types: Command and query objects with proper binding
• Response Types: Response wrappers and DTOs
• File Uploads: IFormFile handling with multipart/form-data
• Collections: Paginated and filtered collection responses
• Validation: Required fields, nullable types, and constraints

File Upload & Form Data

Single and Multiple File Support

public record UploadDocumentsCommand : ICommand<List<DocumentDto>>
{
    [FromForm] public List<IFormFile> Files { get; init; } = [];
    [FromForm] public string Category { get; init; } = string.Empty;
    [FromForm] public bool IsPublic { get; init; } = false;
    [FromQuery] public string? FolderId { get; init; }
}

// Generates proper multipart/form-data schema in OpenAPI
public class UploadDocumentsEndpoint : SingleEndpointBase<UploadDocumentsCommand, List<DocumentDto>>
{
    [HttpPost("documents/upload")]
    public override async Task<Response<List<DocumentDto>>> HandleAsync(...) =>
        await _mediator.Send(request, ct);
}

Integration Examples

With Autofac and Infrastructure Services

// Program.cs - Complete setup
builder.UseAutofacServiceProvider(containerBuilder =>
{
    containerBuilder
        .AddApplicationServices()     // MediatR handlers
        .AddInfrastructureServices(); // Repositories, services
});

builder.Services
    .AddMinimalApiWithSwaggerUI(/* ... */)
    .AddInfrastructureServices(configuration) // Traditional DI
    .AddApplicationServices(configuration);

Command Handler Example

public class CreateUserHandler(
    ICommandRepository repository,
    ICacheService cache,
    ILogger<CreateUserHandler> logger)
    : ICommandHandler<CreateUserCommand, UserDto>
{
    public async Task<Response<UserDto>> Handle(
        CreateUserCommand request, CancellationToken cancellationToken)
    {
        var user = new User
        {
            Name = request.Name,
            Email = request.Email,
            CreatedAt = DateTime.UtcNow
        };

        await repository.AddAsync(user, cancellationToken);
        await repository.SaveChangesAsync(cancellationToken);

        // Invalidate cache
        await cache.RemoveByPatternAsync("users:*");

        logger.LogInformation("Created user {UserId} with email {Email}", 
            user.Id, user.Email);

        return Response<UserDto>.Success(user.ToDto());
    }
}

Architecture Components

Base Classes

• EndpointAbstractBase: Core abstract base with execution framework
• SingleEndpointBase<TRequest, TResponse>: For single item responses
• CollectionEndpointBase<TRequest, TResponse>: For collection responses
• SingleEndpointBase<TRequest>: For responses without specific data

Interface Contracts

• ICommand / ICommand<T>: Command pattern interfaces
• IQueryRequest<T> / IQueryCollectionRequest<T>: Query interfaces
• IEndpoint: Core endpoint interface with HttpContext and Definition

Attribute System

• @HttpGet/@HttpPost/@HttpPut/@HttpDelete: HTTP method routing
• @OpenApiSummary: Documentation and tagging
• @OpenApiParameter/@OpenApiResponse: Detailed API specification
• @FromRoute/@FromQuery/@FromBody/@FromForm/@FromHeader: Parameter binding
• @ApiVersion: Version specification

Requirements & Dependencies

• .NET 9.0 or higher
• MediatR 12.2.0 - CQRS pattern implementation
• Microsoft.AspNetCore.OpenApi 9.0.0 - OpenAPI document generation
• Swashbuckle.AspNetCore 8.1.2 - SwaggerUI integration
• System.Text.Json - JSON serialization
• Microsoft.Extensions.DependencyInjection - Service registration

Integration with Moclawr Ecosystem

Seamless integration with the complete Moclawr framework:

• Moclawr.Core: Extension methods and utilities
• Moclawr.Shared: Response<T> and ResponseCollection<T> models
• Moclawr.Host: Global exception handling and health checks
• Moclawr.EfCore: Repository patterns and Entity Framework integration
• Moclawr.Services.Caching: Response caching for API endpoints
• Moclawr.Services.AWS.S3: File storage integration
• Moclawr.Services.Autofac: Enhanced dependency injection and service discovery

License

This package is licensed under the MIT License.

Note: Version 2.1.2 represents a complete, production-ready MinimalAPI framework with zero hardcoded assumptions. The system dynamically adapts to any project structure while providing enterprise-grade features for API development, documentation, and deployment.