ASP.NET Minimal API OpenAPI

aspnet-minimal-api-openapi skill for programming & development

Category: development Source: github

Building REST APIs with ASP.NET Minimal APIs requires OpenAPI documentation for API consumers. This skill generates OpenAPI specifications from minimal API definitions including endpoint documentation, request/response schemas, parameter descriptions, and authentication requirements enabling comprehensive API documentation with minimal code.

What Is This?

Overview

ASP.NET Minimal API OpenAPI provides tooling and patterns for generating OpenAPI documentation from ASP.NET Minimal API definitions. It handles automatic schema generation from types, endpoint metadata extraction, parameter documentation, response type descriptions, authentication scheme documentation, and Swagger UI integration for interactive exploration.

The skill uses attributes and fluent configuration to enhance generated documentation with descriptions, examples, summaries, and deprecated markers. It generates OpenAPI 3.0 specifications consumable by API clients, documentation tools, and code generators.

This produces comprehensive API documentation automatically from code, keeping documentation synchronized with implementation and enabling API consumer tooling through standardized specifications.

Who Should Use This

.NET developers building REST APIs. API architects designing specifications. Teams documenting APIs. Backend engineers exposing services. Anyone building ASP.NET Minimal APIs.

Why Use It?

Problems It Solves

Manual API documentation becomes outdated quickly. Generated documentation stays synchronized with implementation automatically.

API consumers need specifications for client generation. OpenAPI specs enable tooling and code generation.

Understanding API contracts requires reading code. Interactive documentation makes APIs explorable without code access.

Incomplete documentation confuses consumers. Comprehensive generation ensures completeness.

Core Highlights

Automatic OpenAPI generation from code. Schema generation from .NET types. Endpoint metadata extraction. Parameter and response documentation. Authentication scheme descriptions. Swagger UI integration. OpenAPI 3.0 specification support. Client generation enablement.

How to Use It?

Basic Usage

Define minimal APIs with types and attributes, configure OpenAPI generation, access documentation via Swagger UI.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();
app.UseSwagger();
app.UseSwaggerUI();

app.MapGet("/users/{id}", (int id) => 
    Results.Ok(new User(id, "John")))
    .WithName("GetUser")
    .WithOpenApi();

app.Run();

Specific Scenarios

For comprehensive documentation:

app.MapPost("/users", (CreateUserRequest request) => 
    Results.Created(quot;/users/{1}", new User(1, request.Name)))
    .WithName("CreateUser")
    .WithTags("Users")
    .WithOpenApi(op => {
        op.Summary = "Create new user";
        op.Description = "Creates user with provided details";
        return op;
    });

For authentication:

builder.Services.AddSwaggerGen(options => {
    options.AddSecurityDefinition("Bearer", new() {
        Type = SecuritySchemeType.Http,
        Scheme = "bearer",
        BearerFormat = "JWT"
    });
});

app.MapGet("/secure", () => "Protected")
    .RequireAuthorization()
    .WithOpenApi();

For versioning:

app.MapGroup("/v1")
    .WithTags("V1")
    .MapGet("/users", GetUsersV1);

app.MapGroup("/v2")
    .WithTags("V2")
    .MapGet("/users", GetUsersV2);

Real-World Examples

A team builds microservice API. They define endpoints with minimal APIs, add WithOpenApi configuration for descriptions, generate OpenAPI spec automatically, and publish to API gateway. Frontend team uses spec to generate TypeScript client. Documentation stays current as API evolves.

An API requires authentication documentation. They configure Swagger security definitions for Bearer tokens, mark protected endpoints with RequireAuthorization, generate spec including auth requirements, and consumers understand authentication flow from documentation.

A public API needs comprehensive documentation. They add XML comments, configure Swagger to include descriptions, provide examples for complex types, generate interactive documentation, and publish for external consumers. API becomes easily understandable and explorable.

Advanced Tips

Use XML documentation comments for rich descriptions. Configure Swagger to include auth schemes. Add examples for complex request/response types. Use groups for logical API organization. Version APIs with separate groups or documents. Configure Swagger UI for optimal experience. Export OpenAPI spec for external tools. Keep documentation comprehensive but concise.

When to Use It?

Use Cases

REST API documentation generation. Client SDK generation enablement. API gateway integration. Public API documentation. Internal microservice documentation. API versioning documentation. Authentication flow documentation.

Important Notes

Requirements

ASP.NET 6.0 or later. Minimal API definitions. Swashbuckle.AspNetCore package. Understanding of OpenAPI specification. API design knowledge. Documentation standards awareness.

Usage Recommendations

Add XML documentation for comprehensive descriptions. Configure security schemes appropriately. Provide examples for complex types. Organize endpoints with tags and groups. Version APIs consistently. Test generated documentation accuracy. Export specs for external consumption. Keep documentation current with implementation. Use meaningful endpoint names.

Limitations

Generated docs may need manual enhancement. Complex scenarios require custom configuration. XML comments add verbosity. Some OpenAPI features require explicit configuration. Documentation quality depends on code quality. Requires discipline to maintain. Large APIs generate large specifications.