skills.rest
envoydev
envoydevCOMMUNITY
Explore all skills by this author →
GitHub

dotnet-openapi

Generates OpenAPI documents and serves Scalar docs UIs on ASP.NET Core services.

1|Updated Jun 2, 2026
Search Tags:#openapi#dotnet#swagger#API documentation#asp.net core#scalar#swashbuckle
One-click install
npx skills add https://github.com/envoydev/claude-stack --skill dotnet-openapi-envoydev
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: dotnet-openapi
Source: https://github.com/envoydev/claude-stack/tree/main/stack/skills/dotnet-openapi
Command: npx skills add https://github.com/envoydev/claude-stack --skill dotnet-openapi-envoydev

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? ASP.NET Core services need an accurate, machine-readable OpenAPI document and a browsable docs UI, but hand-written specs drift from the running code and misconfigured generators produce thin, incomplete contracts. ## Core Features & Use Cases - Generator Selection by Framework Floor: Picks Swashbuckle or NSwag on .NET 8 and the built-in Microsoft.AspNetCore.OpenApi with AddOpenApi / MapOpenApi on .NET 9 and up. - Spec Shaping and Security Schemes: Uses document, operation, and schema transformers to declare bearer/JWT security schemes, split versioned documents, and keep schemas accurate via TypedResults and Produces metadata. - Docs UI and Client Generation: Serves a gated Scalar UI and emits the document at build time so consumers generate TypeScript types or typed clients with NSwag, Kiota, or openapi-typescript. - Use Case: When adding API documentation to a new .NET 9 minimal API, use this Skill to wire AddOpenApi with a bearer security transformer, gate the Scalar UI to development, and verify the generated spec lists every expected path. ## Quick Start Use the dotnet-openapi skill to add a generated OpenAPI document with a Bearer security scheme and a development-only Scalar UI to my ASP.NET Core service.

Frequently Asked Questions about dotnet-openapi

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add OpenAPI documentation to an ASP.NET Core API?▼

On .NET 9 and up, call builder.Services.AddOpenApi() and app.MapOpenApi() to serve the document at /openapi/v1.json. On .NET 8, use Swashbuckle with AddSwaggerGen() and UseSwagger() to expose the JSON.

Swashbuckle vs NSwag vs Microsoft.AspNetCore.OpenApi: which generator should I use?▼

Use the built-in Microsoft.AspNetCore.OpenApi on .NET 9+ since it tracks the framework with no third-party dependency. On .NET 8, default to Swashbuckle; choose NSwag only when you also need strongly-typed C# or TypeScript client generation.

Why is my OpenAPI schema empty for minimal API endpoints?▼

Empty schemas happen when handlers return untyped Results.Ok(), which exposes only IResult. Return TypedResults.Ok<T>() and declare outcomes with .Produces<T>() so the generator can see the payload types and status codes.

How do I add a Bearer JWT security scheme to the OpenAPI document?▼

Add an OpenApiSecurityScheme of type HTTP bearer with bearerFormat JWT via a document transformer on the built-in generator, or use AddSecurityDefinition plus AddSecurityRequirement on Swashbuckle. This is documentation only and does not enforce authentication.

Should I expose the Swagger or Scalar docs UI in production?▼

Gate the UI behind an IsDevelopment() check or attach RequireAuthorization() in production. A docs page maps your internal surface, including parameter names and schema shapes, so shipping it open invites scanning.

When should I not hand-edit an OpenAPI specification file?▼

Never hand-edit a checked-in OpenAPI file, because it drifts from the code the moment an endpoint changes and nothing fails when it does. Treat the document as generated output and fix the endpoint metadata instead.

Related Skills

Explore More Software Engineering Skills→
p-o-ke-naep-o-ke-nae

aspnet-minimal-api-openapi

Create ASP.NET Minimal API endpoints with typed results and OpenAPI documentation.

Community
Intermediate
OrchardCMSOrchardCMS
8.2k

orchardcore-nswag-regenerate

Regenerates OrchardCore OpenApi NSwag C# and TypeScript clients and verifies diff stability.

Official
Advanced
medridemedride
1

dotnet-api-auth

Implement JWT Bearer and API key authentication for ASP.NET Core Web APIs.

Official
Advanced
matlockxmatlockx

grpc

Set up Go gRPC services with Buf code generation and scaffolding.

Community
Advanced