aspnet-minimal-api-openapi

github/awesome-copilot

Guides AI agents to build well-structured, well-documented ASP.NET Minimal API endpoints.

What is aspnet-minimal-api-openapi?

This skill guides an AI coding agent to scaffold and refine ASP.NET Minimal API endpoints following best practices for organization, strongly-typed request/response models, and built-in .NET 9 OpenAPI documentation. Use it when building or cleaning up Minimal API endpoints that need proper typing, validation, and Swagger/OpenAPI metadata.

Recommends grouping related endpoints with MapGroup() and endpoint filters
Guides creation of explicit request/response DTOs using records and validation attributes
Promotes strongly-typed parameter binding and use of TypedResults/Results<T1,T2>
Advises on .NET 9 built-in OpenAPI documentation including summaries, descriptions, and operationIds via WithName
Suggests document and schema transformers for servers, tags, security schemes, and schema customization

How to install aspnet-minimal-api-openapi

npx skills add https://github.com/github/awesome-copilot --skill aspnet-minimal-api-openapi

Prerequisites

.NET 9 or later (for built-in OpenAPI document support)
An ASP.NET Core project using Minimal APIs
C# 10+ for language features like record types and nullable annotations

Claude Code

Cursor

Windsurf

Cline

How to use aspnet-minimal-api-openapi

1.Ask the assistant to create or refactor a Minimal API endpoint (e.g., 'add a GET endpoint for orders')
2.Have it group related endpoints using MapGroup() and structure them into endpoint classes or feature folders as the API grows
3.Have it define explicit request/response DTOs (records with validation attributes) instead of using raw types
4.Have it apply TypedResults and Results<T1,T2> for strongly-typed, multi-outcome responses
5.Have it add OpenAPI metadata: WithName for operationIds, [Description()] on properties/parameters, summaries and descriptions
6.Review and wire up any suggested document/schema transformers and ProblemDetailsService/StatusCodePages configuration in your app startup

Use cases

Good for

Adding a new Minimal API endpoint with proper request/response DTOs and validation
Refactoring existing Minimal API endpoints to use TypedResults and Results<T1,T2>
Organizing a growing set of endpoints with MapGroup() and feature-based folders
Enriching OpenAPI documentation with summaries, descriptions, and operationIds
Standardizing error responses using ProblemDetailsService and StatusCodePages

Who it's for

.NET backend developers building ASP.NET Minimal APIs
Engineers needing well-documented OpenAPI/Swagger specs for their APIs
Teams standardizing API endpoint structure and typed responses

aspnet-minimal-api-openapi FAQ

Does this require .NET 9?

It relies on the built-in OpenAPI document support added in .NET 9, so it assumes you're using .NET 9 or later for that feature.

Does this skill generate Swagger UI for me?

No, it provides guidance on structuring code and OpenAPI documentation; it doesn't itself install or configure Swagger UI tooling.

Will this scaffold a full project?

No, it's a set of conventions and best practices to apply when you write Minimal API endpoint code, not a project scaffolding tool.

Is this specific to Minimal APIs or also Controllers?

It's specifically focused on ASP.NET Minimal API endpoints, not controller-based APIs.

Full instructions (SKILL.md)

Source of truth, from github/awesome-copilot.

name: aspnet-minimal-api-openapi description: 'Create ASP.NET Minimal API endpoints with proper OpenAPI documentation'

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

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 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
Define operation summary and description
Add operationIds using the WithName extension 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