ASP.NET Minimal API with OpenAPI
Create well-structured ASP.NET Minimal API endpoints by grouping routes, modeling request and response DTOs, returning typed results, and documenting operations so generated OpenAPI describes real behavior.
Use it for OpenAPI/Swagger documentation and strongly-typed endpoint design.
Treat endpoint filters as the cross-cutting extension point.
When to invoke
- "Create an ASP.NET Minimal API endpoint with OpenAPI docs."
- "Add Swagger documentation for this Minimal API."
- "Use typed results for these endpoints."
- "Group these Minimal API routes."
- "Document request and response models in .NET 9 OpenAPI."
API organization
| Concern |
Recommended approach |
Why it matters |
| Related endpoints |
Group related endpoints using MapGroup() extension. |
Keeps shared route prefixes, tags, authorization, filters, and metadata consistent. |
| Cross-cutting behavior |
Use endpoint filters for validation, logging, authorization checks, or other concerns that do not belong in handlers. |
Prevents duplicated handler boilerplate. |
| Large APIs |
Structure larger APIs with separate endpoint classes or extension methods. |
Keeps Program.cs small and discoverable. |
| Complex domains |
Consider feature-based folders. |
Collocates endpoint mapping, DTOs, validation, and tests by capability. |
Keep handlers thin: parse typed input, call application services, map domain outcomes to HTTP results, and attach metadata.
Request and response types
| Topic |
Rule |
| DTOs |
Define explicit request and response DTOs/models instead of accepting anonymous shapes. |
| Immutability |
Use record types for immutable request/response objects when mutation is unnecessary. |
| Names |
Use meaningful property names that align with API design standards and the public contract. |
| Validation |
Create clear model classes with [Required] and other validation attributes to enforce constraints. |
| Nullability |
Leverage nullable annotations and init-only properties so required and optional data are visible in C# and OpenAPI. |
| Errors |
Use ProblemDetailsService and StatusCodePages to get standard error responses. |
Do not leak EF entities or internal domain models as public API contracts unless the project explicitly treats them as contracts.
Typed result handling
| Need |
API |
Guidance |
| Multiple outcomes |
Results<T1, T2> |
Represent success, validation, not-found, and error outcomes in the method signature. |
| Strong response metadata |
TypedResults |
Prefer TypedResults instead of Results so response types flow into OpenAPI. |
| Route parameters |
Strongly-typed route parameters |
Use explicit type binding such as int id, Guid id, or custom binders where supported. |
| Standard errors |
TypedResults.Problem, TypedResults.ValidationProblem, TypedResults.NotFound |
Align runtime behavior with documented OpenAPI responses. |
OpenAPI documentation
| Documentation item |
How to express it |
| Operation name |
Add operationIds using WithName. |
| Summary and description |
Define operation summary and description on the endpoint metadata supported by the target .NET version. |
| Request/response content types |
Set proper content types for requests and responses. |
| Property and parameter descriptions |
Add descriptions to properties and parameters with [Description()]. |
| Document-wide metadata |
Use document transformers to add servers, tags, security schemes, and other document-level elements. |
| Schema customization |
Use schema transformers to apply customizations to OpenAPI schemas. |
| Built-in support |
Use the built-in OpenAPI document support added in .NET 9 when the project targets it. |
Output template
## ASP.NET Minimal API result
**Status:** created | reviewed | blocked
**Endpoint group:** `<route group or feature>`
| Endpoint | Request type | Response types | OpenAPI metadata |
| --- | --- | --- | --- |
| `<METHOD /route>` | `<DTO or none>` | `Results<T1, T2>` | `WithName`, summary, description, content types |
### Implementation notes
- Grouping: `<MapGroup decision>`
- Validation: `<attributes/filter/service>`
- Error shape: `<ProblemDetails/StatusCodePages behavior>`
### Validation
- `<build/test/openapi command>`: pass | fail | not run
Quality gate
1---2name: aspnet-minimal-api-openapi-23description: Create or review ASP.NET Minimal API endpoints with typed results, DTO validation, endpoint groups, filters, ProblemDetails, and OpenAPI documentation. Use this skill when asked to add Minimal APIs, document endpoints with Swagger/OpenAPI, use .NET 9 built-in OpenAPI, or design request and response types.4---56# ASP.NET Minimal API with OpenAPI78Create well-structured ASP.NET Minimal API endpoints by grouping routes, modeling request and response DTOs, returning typed results, and documenting operations so generated OpenAPI describes real behavior.910Use it for OpenAPI/Swagger documentation and strongly-typed endpoint design.11Treat endpoint filters as the cross-cutting extension point.1213## When to invoke1415- "Create an ASP.NET Minimal API endpoint with OpenAPI docs."16- "Add Swagger documentation for this Minimal API."17- "Use typed results for these endpoints."18- "Group these Minimal API routes."19- "Document request and response models in .NET 9 OpenAPI."2021## API organization2223| Concern | Recommended approach | Why it matters |24| --- | --- | --- |25| Related endpoints | Group related endpoints using `MapGroup()` extension. | Keeps shared route prefixes, tags, authorization, filters, and metadata consistent. |26| Cross-cutting behavior | Use endpoint filters for validation, logging, authorization checks, or other concerns that do not belong in handlers. | Prevents duplicated handler boilerplate. |27| Large APIs | Structure larger APIs with separate endpoint classes or extension methods. | Keeps `Program.cs` small and discoverable. |28| Complex domains | Consider feature-based folders. | Collocates endpoint mapping, DTOs, validation, and tests by capability. |2930Keep handlers thin: parse typed input, call application services, map domain outcomes to HTTP results, and attach metadata.3132## Request and response types3334| Topic | Rule |35| --- | --- |36| DTOs | Define explicit request and response DTOs/models instead of accepting anonymous shapes. |37| Immutability | Use record types for immutable request/response objects when mutation is unnecessary. |38| Names | Use meaningful property names that align with API design standards and the public contract. |39| Validation | Create clear model classes with `[Required]` and other validation attributes to enforce constraints. |40| Nullability | Leverage nullable annotations and init-only properties so required and optional data are visible in C# and OpenAPI. |41| Errors | Use `ProblemDetailsService` and StatusCodePages to get standard error responses. |4243Do not leak EF entities or internal domain models as public API contracts unless the project explicitly treats them as contracts.4445## Typed result handling4647| Need | API | Guidance |48| --- | --- | --- |49| Multiple outcomes | `Results<T1, T2>` | Represent success, validation, not-found, and error outcomes in the method signature. |50| Strong response metadata | `TypedResults` | Prefer `TypedResults` instead of `Results` so response types flow into OpenAPI. |51| Route parameters | Strongly-typed route parameters | Use explicit type binding such as `int id`, `Guid id`, or custom binders where supported. |52| Standard errors | `TypedResults.Problem`, `TypedResults.ValidationProblem`, `TypedResults.NotFound` | Align runtime behavior with documented OpenAPI responses. |5354## OpenAPI documentation5556| Documentation item | How to express it |57| --- | --- |58| Operation name | Add operationIds using `WithName`. |59| Summary and description | Define operation summary and description on the endpoint metadata supported by the target .NET version. |60| Request/response content types | Set proper content types for requests and responses. |61| Property and parameter descriptions | Add descriptions to properties and parameters with `[Description()]`. |62| Document-wide metadata | Use document transformers to add servers, tags, security schemes, and other document-level elements. |63| Schema customization | Use schema transformers to apply customizations to OpenAPI schemas. |64| Built-in support | Use the built-in OpenAPI document support added in .NET 9 when the project targets it. |6566## Output template6768```markdown69## ASP.NET Minimal API result7071**Status:** created | reviewed | blocked72**Endpoint group:** `<route group or feature>`7374| Endpoint | Request type | Response types | OpenAPI metadata |75| --- | --- | --- | --- |76| `<METHOD /route>` | `<DTO or none>` | `Results<T1, T2>` | `WithName`, summary, description, content types |7778### Implementation notes79- Grouping: `<MapGroup decision>`80- Validation: `<attributes/filter/service>`81- Error shape: `<ProblemDetails/StatusCodePages behavior>`8283### Validation84- `<build/test/openapi command>`: pass | fail | not run85```8687## Quality gate8889- [ ] Related endpoints are grouped with `MapGroup()` or the absence of grouping is justified.90- [ ] Request and response contracts use explicit DTOs/models with meaningful names.91- [ ] Validation attributes such as `[Required]` are applied where the public contract requires them.92- [ ] Handlers return `TypedResults` and `Results<T1, T2>` where multiple response types are possible.93- [ ] Standard errors use `ProblemDetailsService`, StatusCodePages, or typed problem results.94- [ ] OpenAPI includes operationIds through `WithName`, summaries/descriptions, content types, and useful schema metadata.95- [ ] Document transformers or schema transformers are used only when endpoint-level metadata is insufficient.
paulasilvatech