openapi-scalar

What problem does it solve?

Many .NET APIs lack consistent, secure, and versioned OpenAPI documentation; this results in inaccurate client contracts, missing security metadata, and exposed documentation in production. This Skill guides teams to replace legacy Swagger setups, generate accurate OpenAPI documents, and present them with a modern Scalar UI while ensuring docs are secure and environment-aware.

Core Features & Use Cases

• Native OpenAPI (.NET 9+) Integration: Configure Microsoft.AspNetCore.OpenApi with document transformers to populate titles, versions, and descriptions for each document.
• Scalar API Documentation UI: Serve a modern, customizable documentation site using Scalar.AspNetCore as a replacement for Swagger UI.
• Security & Production Safety: Add JWT or API key security scheme transformers and require authorization for documentation endpoints in non-development environments.
• Versioning & Build-Time Generation: Register multiple OpenAPI documents for v1/v2 and optionally generate API description files at build time for CI pipelines.
• Use Case: Migrate a project using Swashbuckle to native OpenAPI, add endpoint summaries and tags, configure a Bearer security transformer, and expose a protected Scalar UI for developer teams.

Quick Start

Configure Microsoft.AspNetCore.OpenApi with a document transformer, add a Bearer security scheme transformer, and map the Scalar API reference while requiring authorization for production.