.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

Knowledge Base Lookups

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

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

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)