AutoGineer
Generated banner for Aspnet Minimal API Openapi
Generated logo for Aspnet Minimal API Openapi

Aspnet Minimal API Openapi

GitHubOfficialOriginally contributed by @aaronpowell as prompts/aspnet-minimal-api-openapi.prompt.md; moved into a skill by pull request #761Distributed by GitHub

  • Skill
  • Tool integration
  • Software development
  • MIT
  • No issues found
Download ZIP

From the author

Create ASP.NET Minimal API endpoints with proper OpenAPI documentation
— the description by aaronpowell

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured approach to developing ASP.NET Minimal APIs. It focuses on maintaining clean code organization, implementing robust request and response handling using DTOs, and ensuring comprehensive OpenAPI documentation through .NET native features. The guidance emphasizes type safety, proper validation, and the use of modern C# features to create maintainable and well-documented API endpoints.

What it does

  • Provides patterns for organizing endpoints using MapGroup and feature-based structures.
  • Outlines best practices for defining request and response models using C# records and validation attributes.
  • Instructs on using TypedResults and Results for type-safe endpoint responses.
  • Details how to implement OpenAPI documentation using built-in .NET 9 support.
  • Explains the use of document and schema transformers for advanced OpenAPI customization.

When to use it

  • When starting a new ASP.NET Minimal API project.
  • When refactoring existing endpoints to improve structure and documentation.
  • When you need to ensure your API endpoints are correctly exposed via OpenAPI/Swagger.
  • When implementing consistent error handling and validation across an API.

Advantages

  • Promotes consistent API structure and organization.
  • Enhances API discoverability through standardized OpenAPI documentation.
  • Improves code maintainability by using strongly-typed models and modern C# features.
  • Facilitates better integration with automated API tooling.

Usage examples

“How should I organize my endpoints in a large Minimal API project?”
The agent will suggest using MapGroup for grouping related endpoints and adopting a feature-based folder structure to keep the codebase manageable.
“How do I add OpenAPI documentation to my Minimal API endpoints?”
The agent will guide you on using the built-in .NET 9 OpenAPI support, including adding summaries, descriptions, and using transformers for custom metadata.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/github/aspnet-minimal-api-openapi/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip aspnet-minimal-api-openapi.zip -d .agents/skills

Documentation by aaronpowell

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

Files

Requirements and compatibility

Written for: GitHub Copilot

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Originally contributed by
GitHub avatar of aaronpowell@aaronpowellas prompts/aspnet-minimal-api-openapi.prompt.mdmoved into a skill by pull request #761
Publisher
GitHub (Official)
Distributed by
GitHub
Source
github/awesome-copilot · skills/aspnet-minimal-api-openapi · commit 797337f
Licence
MIT License (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced
Contributors
aaronpowell, CypherHK, derekclair, jamesmontemagno

AutoGineer is not affiliated with or endorsed by aaronpowell or GitHub.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download aspnet-minimal-api-openapi.zip