dotnet-webapi

What it does

Guides creation and modification of ASP.NET Core Web API endpoints with proper HTTP semantics, OpenAPI documentation, and error handling.

How it works

• Recommends using this skill for adding or modifying Web API endpoints implemented with controllers or minimal APIs, wiring up OpenAPI/Swagger metadata, defining request/response DTOs with consistent HTTP status behavior, and adding .http test files.
• Specifies wiring up centralized API error handling middleware or exception mapping.
• Provides detailed input/output DTO conventions (sealed records, XML docs, DateTimeOffset usage) and minimal API validation registration when using .NET 10+.
• Outlines step-by-step implementation guidance: determine API style, define DTOs, implement endpoints (controllers or minimal APIs) with appropriate return types and cancellation handling, wire OpenAPI metadata, configure JSON options and enum serialization, set up OpenAPI without Swashbuckle on .NET 9+, and establish a global error handling strategy.
• Recommends organizing minimal API endpoints by resource with static classes and Map<Resource> patterns, and preferring TypedResults with explicit return types when multiple results are possible.
• Describes status codes for standard operations and guidance for 201 Created responses, cancellation tokens, and endpoint metadata chaining.
• Emphasizes placing exception handling middleware and a dedicated Middleware directory, and using a service layer instead of direct data store injections.

When to use it

• When adding or modifying ASP.NET Core HTTP APIs, including controllers or minimal APIs.
• When wiring up OpenAPI/Swagger metadata and documenting endpoints.
• When creating request/response DTOs and ensuring consistent HTTP status behavior.
• When adding .http test files and configuring global error handling middleware.
• When wiring up centralized API error handling and exception mapping.

What it can touch

• Requires enabling OpenAPI support and using either controllers or minimal APIs as dictated by the project.
• Instructions reference patterns like Program.cs, MapGet, MapPost, TypedResults, JsonStringEnumConverter, and IExceptionHandler implementations, and file organization under Middleware/.

Caveats

• Do not use this skill for non-API tasks such as general C# coding style, EF Core data access or query optimization, frontend/Blazor work, gRPC services, or SignalR hubs.
• It warns against Swashbuckle on .NET 9+ projects and proposes alternatives to OpenAPI configuration.
• The skill prescribes specific DTO naming, XML docs, and DateTimeOffset usage to align with OpenAPI docs; deviations from these conventions may reduce compatibility with the guidance.