aspnet-minimal-api-openapi
Scannednpx machina-cli add skill github/awesome-copilot/aspnet-minimal-api-openapi --openclawASP.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
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 - Use the ProblemDetailsService and StatusCodePages to get standard error responses
Type Handling
- Use strongly-typed route parameters with explicit type binding
- Use
Results<T1, T2>to represent multiple response types - Return
TypedResultsinstead ofResultsfor 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
- Define operation summary and description
- Add operationIds using the
WithNameextension method - Add descriptions to properties and parameters with
[Description()] - 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
Source
git clone https://github.com/github/awesome-copilot/blob/main/plugins/csharp-dotnet-development/skills/aspnet-minimal-api-openapi/SKILL.mdView on GitHub Overview
This skill guides building well-structured ASP.NET Minimal API endpoints with correct types and comprehensive OpenAPI documentation. It emphasizes organizing endpoints with MapGroup, applying endpoint filters, and structuring APIs into endpoint classes or feature-based folders. It also highlights strong typing, validation attributes, and leveraging .NET 9 OpenAPI features to produce rich, client-friendly docs.
How This Skill Works
Define explicit request and response DTOs (prefer records) with validation attributes like [Required]. Use strongly-typed route parameters and return either Results<T1, T2> or TypedResults to express multiple response types, leveraging init-only properties and nullable annotations. Enable OpenAPI via .NET 9 features, annotate operations with summaries, descriptions, and operationIds (WithName), and apply document/schema transformers to customize servers, tags, and schemas.
When to Use It
- Starting a new Minimal API project that needs clean OpenAPI docs for clients
- When you require strict input validation and explicit DTOs
- To keep large APIs maintainable by grouping endpoints and separating concerns
- When you need multiple possible response types (success, error) using Results<T1,T2> or TypedResults
- When you want to customize the generated OpenAPI with servers, tags, and security schemes via transformers
Quick Start
- Step 1: Define DTOs for requests and responses (prefer records), add validation attributes, and map endpoints using MapGroup with strongly-typed route parameters
- Step 2: Annotate operations with summaries, descriptions, and operationIds using WithName; describe properties with Description attributes and set proper content types
- Step 3: Enable .NET 9 OpenAPI support, apply document/schema transformers, run the app, and verify the Swagger UI
Best Practices
- Group endpoints with MapGroup to keep routes organized
- Define explicit DTOs with validation attributes and meaningful property names
- Prefer record types for immutable request/response objects
- Use strongly-typed route parameters and appropriate Result<...> patterns
- Utilize .NET 9 OpenAPI features: operation summaries, WithName, Description attributes, correct content types, and transformers
Example Use Cases
- E-commerce product create/update endpoints with OpenAPI documentation
- User authentication and profile endpoints with typed requests and detailed error responses
- Order processing endpoints demonstrating multiple response types (Created, BadRequest, NotFound)
- Inventory service endpoints annotated with servers, tags, and security schemes
- Blog API with grouped endpoints and descriptive OpenAPI metadata
