Scalar API Docs — Replacing Swagger With a Modern Developer Experience

Scalar vs Swagger UI:
  ✓ Modern, readable layout — collapsible, searchable, syntax-highlighted
  ✓ Built-in API client (send requests without copy-pasting curl)
  ✓ Multiple theming options out of the box
  ✓ First-class support for .NET's built-in OpenAPI (`Microsoft.AspNetCore.OpenApi`)
  ✓ No Swashbuckle dependency — lighter, actively maintained
  ✓ Works with the .NET 9+ `AddOpenApi()` built-in

<!-- Api.csproj -->
<PackageReference Include="Scalar.AspNetCore" Version="2.*" />

// Api/Program.cs
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();   // .NET 9+ built-in OpenAPI
// ... other services

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();               // exposes /openapi/v1.json
    app.MapScalarApiReference();    // exposes /scalar/v1 UI
}

app.UseAuthentication();
app.UseAuthorization();
app.MapControllers();
app.Run();

// Api/Program.cs
app.MapScalarApiReference(options =>
{
    options.Title       = "SystemForge API";
    options.Theme       = ScalarTheme.Purple;
    options.DefaultHttpClient = new(ScalarTarget.CSharp, ScalarClient.HttpClient);
    options.Authentication = new ScalarAuthenticationOptions
    {
        PreferredSecurityScheme = "Bearer",
    };
});

// Api/Controllers/PatientsController.cs
using Microsoft.AspNetCore.Http;

[ApiController]
[Route("api/patients")]
[Authorize]
[Tags("Patients")]   // groups endpoints in Scalar sidebar
public sealed class PatientsController : ControllerBase
{
    [HttpPost]
    [Authorize(Roles = "Clinician,Admin")]
    [ProducesResponseType<object>(StatusCodes.Status201Created)]
    [ProducesResponseType<ProblemDetails>(StatusCodes.Status409Conflict)]
    [ProducesResponseType<ProblemDetails>(StatusCodes.Status422UnprocessableEntity)]
    [EndpointSummary("Register a new patient")]
    [EndpointDescription("Creates a patient record. MRN must be unique across the system.")]
    public async Task<IActionResult> Create(
        CreatePatientRequest request, CancellationToken ct)
    { ... }

    [HttpGet("{id:guid}")]
    [ProducesResponseType<PatientResponse>(StatusCodes.Status200OK)]
    [ProducesResponseType<ProblemDetails>(StatusCodes.Status404NotFound)]
    [EndpointSummary("Get patient by ID")]
    public async Task<IActionResult> GetById(Guid id, CancellationToken ct)
    { ... }

    [HttpGet]
    [ProducesResponseType<PagedResult<PatientListItem>>(StatusCodes.Status200OK)]
    [EndpointSummary("List active patients")]
    [EndpointDescription("Returns paginated list. Supports optional search by name or MRN.")]
    public async Task<IActionResult> List(
        [FromQuery] string? search,
        [FromQuery] int page     = 1,
        [FromQuery] int pageSize = 20,
        CancellationToken ct     = default)
    { ... }
}

// Api/OpenApi/AddSecuritySchemeTransformer.cs
using Microsoft.AspNetCore.OpenApi;
using Microsoft.OpenApi.Models;

public sealed class AddSecuritySchemeTransformer : IOpenApiDocumentTransformer
{
    public Task TransformAsync(
        OpenApiDocument document,
        OpenApiDocumentTransformerContext context,
        CancellationToken ct)
    {
        document.Components ??= new OpenApiComponents();
        document.Components.SecuritySchemes["Bearer"] = new OpenApiSecurityScheme
        {
            Type         = SecuritySchemeType.Http,
            Scheme       = "bearer",
            BearerFormat = "JWT",
            Description  = "Enter your JWT access token.",
        };

        // Apply globally so all endpoints require auth by default
        document.SecurityRequirements.Add(new OpenApiSecurityRequirement
        {
            {
                new OpenApiSecurityScheme
                {
                    Reference = new OpenApiReference
                    {
                        Type = ReferenceType.SecurityScheme,
                        Id   = "Bearer",
                    }
                },
                []
            }
        });

        return Task.CompletedTask;
    }
}

// Registration
builder.Services.AddOpenApi(options =>
{
    options.AddDocumentTransformer<AddSecuritySchemeTransformer>();
});

// If you add API versioning:
builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1);
    options.ReportApiVersions = true;
    options.AssumeDefaultVersionWhenUnspecified = true;
}).AddApiExplorer(options =>
{
    options.GroupNameFormat           = "'v'V";
    options.SubstituteApiVersionInUrl = true;
});

// Multiple Scalar UIs, one per version
app.MapScalarApiReference("v1", options => options.Title = "SystemForge API v1");
app.MapScalarApiReference("v2", options => options.Title = "SystemForge API v2");

// In production, Scalar should be disabled
if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    app.MapScalarApiReference();
}
// If you want it in staging for QA, use an explicit environment check or feature flag