dotnet-webapi

Name: dotnet-webapi
Author: managedcode

461stars35forks

How to install dotnet-webapi?

managedcode/dotnet-skills/dotnet-webapi

$npx -y skills add managedcode/dotnet-skills --skill dotnet-webapi

Installs into the current project.

Summary

Guides creation and modification of ASP.NET Core Web API endpoints with correct HTTP semantics, OpenAPI metadata, and error handling. USE FOR: adding new API endpoints (controllers or minimal APIs), wiring up OpenAPI/Swagger, creating .http test files, setting up global error han

Files · 1

View on GitHub

SKILL.md

1	# ASP.NET Core Web API
2
3	Produce well-structured ASP.NET Core Web API endpoints with proper HTTP
4	semantics, OpenAPI documentation, and error handling.
5
6	## When to Use
7
8	Use this skill when working on ASP.NET Core HTTP APIs, including:
9
10	- adding or modifying Web API endpoints implemented with controllers or minimal APIs;
11	- wiring up OpenAPI/Swagger metadata and endpoint documentation;
12	- defining request/response DTOs and consistent HTTP status code behavior;
13	- adding `.http` files or similar request-based API testing artifacts;
14	- configuring centralized API error handling middleware or exception mapping.
15
16	## When Not to Use
17
18	Do not use this skill for:
19
20	- general C# coding style or non-API refactoring;
21	- EF Core data modeling or query optimization work; use `optimizing-ef-core-queries`;
22	- frontend, Razor, or Blazor UI changes;
23	- gRPC services;
24	- SignalR hubs or real-time messaging flows.
25
26	## Inputs / prerequisites
27
28	Before applying this skill, gather the project context needed to match the
29	existing API style and wiring:
30
31	- the ASP.NET Core entry point, typically `Program.cs`;
32	- any existing controllers, especially classes inheriting `ControllerBase` or
33	using `[ApiController]`;
34	- any existing minimal API registrations such as `app.MapGet`, `app.MapPost`,
35	`app.MapPut`, or `app.MapDelete`;
36	- related DTO, model, validation, and error-handling types already used by the project;
37	- available build, run, and test commands so changes can be verified.
38
39	If the user asks for a new endpoint, inspect the current project structure first
40	so the implementation follows the established conventions rather than mixing styles.
41	## Workflow
42
43	### Step 1: Determine the API style
44
45	Scan the project for existing endpoint patterns before writing any code.
46
47	1. Search for classes inheriting `ControllerBase` or decorated with `[ApiController]`.
48	2. Search `Program.cs` or endpoint files for `app.MapGet`, `app.MapPost`, etc.
49	3. If the project already uses controllers, continue with controllers.
50	4. If the project already uses minimal APIs, continue with minimal APIs.
51	5. If neither exists (new project), default to minimal APIs unless the user
52	explicitly requests controllers.
53
54	Do not mix styles in the same project.
55
56	### Step 2: Define request and response types
57
58	Create dedicated types for API input and output. Never expose EF Core entities
59	directly in request or response bodies.
60
61	Use `sealed record` for all DTOs. Records enforce immutability, provide
62	value-based equality, and produce concise code. Seal them to prevent unintended
63	inheritance and enable JIT devirtualization (CA1852).
64
65	Naming convention:
66
67	\| Role \| Convention \| Example \|
68	\|------\|-----------\|---------\|
69	\| Input (create) \| `Create{Entity}Request` \| `CreateProductRequest` \|
70	\| Input (update) \| `Update{Entity}Request` \| `UpdateProductRequest` \|
71	\| Output (single) \| `{Entity}Response` \| `ProductResponse` \|
72	\| Output (list) \| `{Entity}ListResponse` \| `ProductListResponse` \|
73
74	XML doc comments on all DTOs: Add `<summary>` XML doc comments to every
75	request and response type exposed in the API. These comments are automatically
76	included in the generated OpenAPI specification, producing richer documentation
77	without extra metadata calls.
78
79	Reference: https://learn.microsoft.com/en-us/aspnet/core/fundamentals/openapi/openapi-comments
80
81	Date and time values — use `DateTimeOffset`: When a DTO includes a date or
82	time property, always use `DateTimeOffset` instead of `DateTime`.
83	`DateTimeOffset` preserves the UTC offset, avoids ambiguous timezone
84	conversions, and serializes to ISO 8601 with offset information in JSON — which
85	is what API consumers expect.
86
87	Reference: https://learn.microsoft.com/en-us/dotnet/api/system.datetimeoffset
88	JSON serialization options — preserve existing behavior by default: For
89	existing APIs, do not introduce stricter serialization/deserialization settings
90	unless the project already uses them or the user explicitly asks for them. Settings
91	such as case-sensitive property matching and strict number handling can break
92	existing clients. For new projects, or when strict JSON handling is explicitly
93	requested, configure options like the following to minimize the potential of
94	processing malicious requests:
95
96	```csharp
97	// Apply these settings only for new projects, when the existing project already
98	// uses them, or when the user explicitly requests stricter JSON behavior.
99	builder.Services.ConfigureHttpJsonOptions(option

People who liked this also viewed

6 picks

Type

dotnet-webapi

461stars35forks

View on GitHub

How to install dotnet-webapi?

managedcode/dotnet-skills/dotnet-webapi

$npx -y skills add managedcode/dotnet-skills --skill dotnet-webapi

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# ASP.NET Core Web API
2
3	Produce well-structured ASP.NET Core Web API endpoints with proper HTTP
4	semantics, OpenAPI documentation, and error handling.
5
6	## When to Use
7
8	Use this skill when working on ASP.NET Core HTTP APIs, including:
9
10	- adding or modifying Web API endpoints implemented with controllers or minimal APIs;
11	- wiring up OpenAPI/Swagger metadata and endpoint documentation;
12	- defining request/response DTOs and consistent HTTP status code behavior;
13	- adding `.http` files or similar request-based API testing artifacts;
14	- configuring centralized API error handling middleware or exception mapping.
15
16	## When Not to Use
17
18	Do not use this skill for:
19
20	- general C# coding style or non-API refactoring;
21	- EF Core data modeling or query optimization work; use `optimizing-ef-core-queries`;
22	- frontend, Razor, or Blazor UI changes;
23	- gRPC services;
24	- SignalR hubs or real-time messaging flows.
25
26	## Inputs / prerequisites
27
28	Before applying this skill, gather the project context needed to match the
29	existing API style and wiring:
30
31	- the ASP.NET Core entry point, typically `Program.cs`;
32	- any existing controllers, especially classes inheriting `ControllerBase` or
33	using `[ApiController]`;
34	- any existing minimal API registrations such as `app.MapGet`, `app.MapPost`,
35	`app.MapPut`, or `app.MapDelete`;
36	- related DTO, model, validation, and error-handling types already used by the project;
37	- available build, run, and test commands so changes can be verified.
38
39	If the user asks for a new endpoint, inspect the current project structure first
40	so the implementation follows the established conventions rather than mixing styles.
41	## Workflow
42
43	### Step 1: Determine the API style
44
45	Scan the project for existing endpoint patterns before writing any code.
46
47	1. Search for classes inheriting `ControllerBase` or decorated with `[ApiController]`.
48	2. Search `Program.cs` or endpoint files for `app.MapGet`, `app.MapPost`, etc.
49	3. If the project already uses controllers, continue with controllers.
50	4. If the project already uses minimal APIs, continue with minimal APIs.
51	5. If neither exists (new project), default to minimal APIs unless the user
52	explicitly requests controllers.
53
54	Do not mix styles in the same project.
55
56	### Step 2: Define request and response types
57
58	Create dedicated types for API input and output. Never expose EF Core entities
59	directly in request or response bodies.
60
61	Use `sealed record` for all DTOs. Records enforce immutability, provide
62	value-based equality, and produce concise code. Seal them to prevent unintended
63	inheritance and enable JIT devirtualization (CA1852).
64
65	Naming convention:
66
67	\| Role \| Convention \| Example \|
68	\|------\|-----------\|---------\|
69	\| Input (create) \| `Create{Entity}Request` \| `CreateProductRequest` \|
70	\| Input (update) \| `Update{Entity}Request` \| `UpdateProductRequest` \|
71	\| Output (single) \| `{Entity}Response` \| `ProductResponse` \|
72	\| Output (list) \| `{Entity}ListResponse` \| `ProductListResponse` \|
73
74	XML doc comments on all DTOs: Add `<summary>` XML doc comments to every
75	request and response type exposed in the API. These comments are automatically
76	included in the generated OpenAPI specification, producing richer documentation
77	without extra metadata calls.
78
79	Reference: https://learn.microsoft.com/en-us/aspnet/core/fundamentals/openapi/openapi-comments
80
81	Date and time values — use `DateTimeOffset`: When a DTO includes a date or
82	time property, always use `DateTimeOffset` instead of `DateTime`.
83	`DateTimeOffset` preserves the UTC offset, avoids ambiguous timezone
84	conversions, and serializes to ISO 8601 with offset information in JSON — which
85	is what API consumers expect.
86
87	Reference: https://learn.microsoft.com/en-us/dotnet/api/system.datetimeoffset
88	JSON serialization options — preserve existing behavior by default: For
89	existing APIs, do not introduce stricter serialization/deserialization settings
90	unless the project already uses them or the user explicitly asks for them. Settings
91	such as case-sensitive property matching and strict number handling can break
92	existing clients. For new projects, or when strict JSON handling is explicitly
93	requested, configure options like the following to minimize the potential of
94	processing malicious requests:
95
96	```csharp
97	// Apply these settings only for new projects, when the existing project already
98	// uses them, or when the user explicitly requests stricter JSON behavior.
99	builder.Services.ConfigureHttpJsonOptions(option

People who liked this also viewed

6 picks

Type