aspnet-minimal-api-openapi

ASP.NET Minimal API with OpenAPI

Your goal is to help me create well-structured ASP.NET Minimal API endpoints with correct types and comprehensive OpenAPI/Swagger documentation.

API Organization

• Group related endpoints using MapGroup() extension
• Use endpoint filters for cross-cutting concerns
• Structure larger APIs with separate endpoint classes
• Consider using a feature-based folder structure for complex APIs

Security

• Apply RequireAuthorization() to any endpoint that requires an authenticated caller
• Consider rate-limiting middleware (app.UseRateLimiter()) for publicly accessible endpoints
• Validate and sanitize all inputs via [Required], [MaxLength], [Range], and similar data-annotation attributes on DTOs

Request and Response Types

• Define explicit request and response DTOs/models
• Create clear model classes with proper validation attributes
• Use record types for immutable request/response objects
• Use meaningful property names that align with API design standards
• Apply [Required] and other validation attributes to enforce constraints
• For RFC 7807-compliant error responses, register builder.Services.AddProblemDetails() in the service container and add app.UseStatusCodePages() middleware in the pipeline — both steps are required

Type Handling

• Use strongly-typed route parameters with explicit type binding
• Use Results<T1, T2> to represent multiple response types
• Return TypedResults instead of Results for strongly-typed responses
• Leverage C# 10+ features like nullable annotations and init-only properties

OpenAPI Documentation

• Use the built-in OpenAPI document support added in .NET 9 (requires .NET 9+ SDK; for earlier SDK versions use Swashbuckle: Swashbuckle.AspNetCore)
• Define operation summary and description
• Add operationIds using the WithName extension method
• Add descriptions to properties and parameters with [Description()] (requires using System.ComponentModel;)
• Set proper content types for requests and responses
• Use document transformers to add elements like servers, tags, and security schemes
• Use schema transformers to apply customizations to OpenAPI schemas