aspnet-minimal-api-openapi

This skill guides an AI assistant in building well-structured ASP.NET Minimal API endpoints paired with comprehensive OpenAPI/Swagger documentation. It addresses a common gap in Minimal API development: producing endpoints that are strongly typed, correctly organized, and self-documenting rather than ad-hoc route handlers with weak types and missing schema metadata. The guidance is framed as a set of conventions the assistant should apply when a developer asks it to create or refine Minimal API code.

The skill covers several concrete areas. For API organization it recommends grouping related endpoints with MapGroup(), using endpoint filters for cross-cutting concerns, and adopting feature-based folder structures for larger APIs. For request and response handling it advises explicit DTOs, record types for immutable payloads, validation attributes like [Required], and standardized error responses via ProblemDetailsService and StatusCodePages. For type handling it promotes strongly-typed route parameters, Results<T1, T2> for multiple response types, TypedResults, and modern C# 10+ features. The OpenAPI section leans on .NET 9's built-in OpenAPI support, operation summaries, WithName for operationIds, [Description] attributes, and document/schema transformers for servers, tags, and security schemes.

The target users are .NET backend developers and teams building HTTP APIs who want idiomatic, documented Minimal API code. It is best suited to greenfield endpoint creation, refactoring loosely typed handlers, and standardizing API documentation across a codebase. It is a single-document convention reference rather than executable tooling, so it shapes generated code rather than running or deploying anything.