michaelalber/minimal-api-scaffolder

.NET 10 Minimal API Scaffolder

"Minimal APIs are ideal for microservices and apps that want to include only the minimum files, features, and dependencies in ASP.NET Core." -- Microsoft Documentation

"A good API is not just easy to use but also hard to misuse." -- Joshua Bloch

Core Philosophy

This skill scaffolds and maintains Minimal API endpoints in .NET 10 projects with OpenAPI documentation, versioning, and security configured from the start. Every API begins with a clear contract, validated inputs, and documented responses.

Non-Negotiable Constraints:

1. OpenAPI-First Design — Every endpoint must have OpenAPI metadata: name, summary, request/response types, and status codes. No endpoint ships without .WithName(), .WithSummary(), and .Produces<T>().
2. Versioning from Day One — API versioning is configured at project creation, not retrofitted. Every endpoint group includes a version segment. There is no "we'll add versioning later."
3. Security by Default — Groups default to .RequireAuthorization(). Anonymous access is an explicit opt-in via .AllowAnonymous(), never an implicit default.
4. Convention over Configuration — Every new endpoint group mirrors the established convention: group creation with tags, OpenAPI metadata, typed results, and FluentValidation integration.
5. Typed Results, Not Raw Responses — All handlers return TypedResults with explicit union return types (Results<Ok<T>, NotFound, ValidationProblem>). No raw IResult, no untyped Results.Ok(), no status code magic numbers.

Domain Principles Table

| # | Principle | Description | Priority | |---|-----------|-------------|----------| | 1 | Endpoint Grouping | Related endpoints are organized into static extension method classes (e.g., UsersEndpoints). Each group maps a resource to a route prefix with shared tags, authorization, and OpenAPI settings. | Critical | | 2 | Request/Response Models | All request and response types are C# records. Request models use [AsParameters] for GET queries. No anonymous objects, no dynamic, no Dictionary<string, object>. | Critical | | 3 | FluentValidation Integration | Every mutating endpoint (POST, PUT, PATCH) injects and executes IValidator<TRequest> before processing. Validation is explicit in the handler, not hidden in middleware. | Critical | | 4 | OpenAPI Documentation | Every endpoint declares .WithName(), .WithSummary(), .Produces<T>() for all possible status codes, and .Accepts<T>() for request bodies. | Critical | | 5 | Versioning Strategy | The project chooses a versioning strategy at setup time and applies it consistently. URL versioning (/api/v{version:apiVersion}/) is the recommended default. | High | | 6 | Authorization Patterns | Endpoint groups default to requiring authorization. Individual endpoints may override with specific policies or .AllowAnonymous(). Policies are defined in Program.cs. | Critical | | 7 | Rate Limiting | Public and high-traffic endpoints configure rate limiting policies defined as named policies in Program.cs and applied with .RequireRateLimiting(). | High | | 8 | Error Handling | Errors return RFC 7807 Problem Details via TypedResults.Problem() or TypedResults.ValidationProblem(). A global exception handler produces consistent application/problem+json responses. | High | | 9 | CORS Configuration | CORS origins are explicitly configured per environment. Never use AllowAnyOrigin() in production. Production must whitelist specific origins loaded from configuration. | High | | 10 | Health Checks | Every API project includes health check endpoints (/health, /health/ready, /health/live) mapped with .AllowAnonymous(). Database connectivity is included in readiness checks. | Medium |

Knowledge Base Lookups

| Query | When to Call | |-------|--------------| | search_knowledge("ASP.NET Core Minimal API endpoint group TypedResults .NET 10") | At SCAFFOLD phase — confirms current Minimal API patterns and TypedResults syntax | | search_knowledge("ASP.NET Core API versioning URL header query string") | During CONFIGURE phase — authoritative versioning strategies and setup | | search_knowledge("ASP.NET Core authentication JWT bearer authorization policy") | During SECURE phase — confirms authentication pipeline and policy setup | | search_knowledge("OpenAPI Swagger ASP.NET Core endpoint metadata WithName Produces") | During DOCUMENT phase — authoritative OpenAPI metadata decoration patterns | | search_knowledge("ASP.NET Core rate limiting policy RequireRateLimiting") | When configuring rate limiting — confirms rate limiter registration and application | | search_knowledge("ASP.NET Core health checks ready live endpoints") | When scaffolding health checks — confirms health check endpoint patterns |

Search before each scaffold phase. Generated code must use KB-confirmed API signatures — never training-data assumptions about .NET versioned APIs. Cite source paths in generated file headers.

Workflow

The scaffold lifecycle flows: CONFIGURE → SCAFFOLD → SECURE → DOCUMENT. Each phase has a verification checklist before advancing to the next.

Phase 1: CONFIGURE

Set up the project foundation before any endpoints are created.

• [ ] Create or verify .csproj with required packages (see references/endpoint-patterns.md)
• [ ] Configure Program.cs with service registrations: OpenAPI, versioning, FreeMediator, FluentValidation, DbContext
• [ ] Set up authentication and authorization pipeline
• [ ] Configure API versioning strategy (URL recommended)
• [ ] Register rate limiting policies
• [ ] Configure CORS for target environments

Phase 2: SCAFFOLD

Create endpoint groups, request/response models, and validators.

• [ ] Create endpoint group static class with extension method pattern
• [ ] Define all CRUD operations with typed results
• [ ] Create request records for each mutating operation
• [ ] Create response DTOs for each query operation
• [ ] Implement FluentValidation validators for all request models
• [ ] Wire endpoint group into Program.cs via api.Map{Resource}Endpoints()

Phase 3: SECURE

Apply authorization, rate limiting, and CORS to all endpoints.

• [ ] Apply .RequireAuthorization() to endpoint groups
• [ ] Define and apply specific policies for sensitive operations
• [ ] Apply rate limiting to public-facing or high-traffic endpoints
• [ ] Verify CORS is configured for all consuming origins
• [ ] Add health check endpoints with anonymous access
• [ ] Verify authentication middleware is in the pipeline

Phase 4: DOCUMENT

Ensure every endpoint is fully documented via OpenAPI metadata.

• [ ] Verify every endpoint has .WithName() and .WithSummary()
• [ ] Verify every endpoint declares all .Produces<T>() responses
• [ ] Add .WithDescription() for complex endpoints
• [ ] Test Swagger UI renders correctly for all versions
• [ ] Verify versioned Swagger docs are accessible
• [ ] Confirm request/response schemas appear in OpenAPI spec

State Block Format

<api-scaffold-state>
mode: SCAFFOLD
project_name: MyApp.Api
dotnet_version: net10.0
endpoints_created: [UsersEndpoints]
versioning_strategy: url
auth_configured: true
openapi_configured: true
last_action: Scaffolded UsersEndpoints with full CRUD
next_action: Create OrdersEndpoints group
</api-scaffold-state>

Output Templates

## API Project: [Name] | .NET 10 | Versioning: [URL/Header/Query] | Auth: [JWT/Azure AD]
Packages: Swashbuckle, Asp.Versioning.Http, FluentValidation, FreeMediator

## Endpoint Group: [Resource]
Base Path: /api/v{version}/[resource] | Auth: Required | Rate Limited: [Yes/No]
| Method | Path | Name | Request Type | Response Type | Auth Override |
| GET / | GET /{id} | POST / | PUT /{id} | DELETE /{id} |
Error responses: 400 Validation | 401 Auth | 403 Forbidden | 404 Not Found | 500 Server Error

Full templates (Project Setup Checklist with packages, Endpoint Group Report with request/response schemas, Validation Report, API Documentation Summary): references/endpoint-patterns.md

AI Discipline Rules

Always add FluentValidation to mutating endpoints. Every POST, PUT, and PATCH handler must inject IValidator<TRequest>, call ValidateAsync() before any business logic, and return TypedResults.ValidationProblem(validation.ToDictionary()) on failure. The return type must be a union type — Results<Created<T>, ValidationProblem> — not raw IResult. Never rely on model binding validation alone.

Never create endpoints without OpenAPI metadata. Every endpoint must have .WithName("OperationId"), .WithSummary("brief description"), .Produces<T>(statusCode) for every possible response, and .Accepts<T>() for request bodies. An endpoint without this metadata is invisible to API consumers and tooling.

Always configure CORS explicitly per environment. Never use AllowAnyOrigin() outside development. Origins must be loaded from configuration, not hardcoded. Apply CORS in the middleware pipeline before authentication. Allow credentials only when specific origins are listed.

Use TypedResults with union return types. All handlers must return TypedResults with explicit union types declared in the method signature (Results<Ok<UserDto>, NotFound>). No raw strings, magic status codes, or untyped IResult in endpoint bodies.

Enforce structural versioning and one group per resource. Version segments must appear in the route template — use app.NewVersionedApi() with .HasApiVersion() on groups. One Map{Resource}Endpoints() extension method per resource, called from a single location in Program.cs. When a breaking change occurs, create a new version-specific endpoint class; never add conditional logic inside an existing handler.

Anti-Patterns Table

| # | Anti-Pattern | Problem | Correct Approach | |---|-------------|---------|------------------| | 1 | Fat Program.cs | All registrations and middleware in one massive file | Extract endpoint groups to static extension classes | | 2 | Endpoints Without Validation | Request data flows directly to business logic without validation | Always inject and call IValidator<T> in mutating endpoints | | 3 | Missing OpenAPI Tags | Endpoints appear ungrouped in Swagger UI, making the API undiscoverable | Apply .WithTags() at group level, .WithName()/.WithSummary() on every endpoint | | 4 | Hardcoded CORS Origins | Origins embedded in Program.cs cannot change per environment | Load origins from appsettings.json or environment variables | | 5 | No Versioning Strategy | API changes break existing clients with no migration path | Configure versioning at project creation; use URL versioning as default | | 6 | Mixing Controllers and Minimal APIs | Two routing systems in one project create confusion about conventions | Choose one approach per project | | 7 | Returning Raw Strings | Results.Ok("success") provides no type safety and no OpenAPI schema | Use TypedResults.Ok(typedObject) with strongly typed response records | | 8 | Catch-All Exception Handlers in Endpoints | try/catch in every handler duplicates error handling logic | Use global exception handler middleware; let exceptions propagate | | 9 | Anonymous Endpoints by Default | Forgetting .RequireAuthorization() leaves endpoints publicly accessible | Apply auth at the group level; .AllowAnonymous() as explicit opt-in | | 10 | Inline Lambda Handlers | Complex logic inside MapGet("/", async (ctx) => {...}) is untestable | Extract handlers to named static methods; inject dependencies as parameters |

Error Recovery

Project already has controllers: Do NOT convert existing controllers in place. Create a Features/ directory alongside existing Controllers/. Configure both app.MapControllers() and minimal API groups in Program.cs. Migrate one resource at a time — create the minimal API endpoint group, verify it works, then deprecate the controller. Ask the developer before mixing paradigms; a gradual migration is acceptable, a hybrid architecture with no migration plan is not.

Conflicting versioning approaches (URL in some places, header in others): Identify the dominant strategy already in use. Configure ApiVersionReader.Combine() to support existing clients during migration. Standardize all new endpoints on URL versioning. Document the canonical approach. Never remove a working version reader without a client migration plan.

OpenAPI generation failures (Swagger UI fails or shows missing schemas): Check for endpoints missing .Produces<T>() — Swashbuckle cannot infer response types from minimal APIs. Verify all response types are public records (internal types are invisible). Check for duplicate .WithName() values (operation IDs must be unique). Inspect /swagger/v1/swagger.json directly for schema errors. Verify app.UseSwagger() and app.UseSwaggerUI() are in the correct pipeline order.

Rate limiting not taking effect: Verify app.UseRateLimiter() is in the pipeline after routing and before auth. Confirm rate limiter policy names match the names used in .RequireRateLimiting("PolicyName"). Test under load with bombardier or hey. Verify the OnRejected handler returns 429 responses.

Integration with Other Skills

| Skill | Integration Point | When to Use | |-------|-------------------|-------------| | dotnet-vertical-slice | Feature architecture for handlers behind endpoints | Scaffold CQRS handlers, commands, queries, and validators that endpoint groups delegate to | | dotnet-architecture-checklist | Review scaffolded API projects | Run after scaffolding to verify architectural best practices | | test-scaffold | Generate API integration tests | Create test classes exercising endpoints via WebApplicationFactory<Program> | | dotnet-security-review | Security audit of API configuration | Verify JWT configuration, authorization policies, CORS settings, and rate limiting | | ef-migration-manager | Database setup for API data access | Use when endpoints need new entities or schema changes |

References: references/endpoint-patterns.md (full endpoint group templates, request models, validators, OpenAPI patterns, error handling) | references/versioning-strategies.md (URL/header/query versioning with deprecation) | references/security-patterns.md (authorization, rate limiting, CORS, health checks, JWT setup)