Modern API Documentation with OpenAPI 3.1 and Scalar

Legacy Swagger/Swashbuckle setups create two major problems in modern .NET systems:

1. Cold-Start Latency Spikes: Scanning thousands of controllers via runtime reflection adds seconds to startup time;
2. Native AOT Incompatibility: Heavy reflection frequently fails under AOT trimming, causing runtime crashes.

BitzOrcas.Modern pairs ASP.NET Core OpenAPI 3.1 with the modern Scalar interactive client: All route metadata is extracted during compilation via [GenerateEndpoint], guaranteeing zero reflection and lightning-fast startups.

Compile-Time OpenAPI and Scalar Flow

Step 1: Declarative Endpoint Contracts

Simply annotate Command or Query records with [GenerateEndpoint]:

using BitzOrcas.Application.Abstractions;
using BitzOrcas.Domain.Results;
using BitzOrcas.Endpoint.Attributes;
using Mediator;

namespace BitzOrcas.Ticket.Application.Queries;

// 1. Declarative endpoint contract: Source Generator extracts OpenAPI 3.1 metadata at compile time
// 2. Generates Minimal API endpoint mapping and Scalar UI bindings
[GenerateEndpoint(HttpRoute.Get, "/api/tickets/{id}", Tag = "Tickets")]
public sealed record GetTicketByIdQuery(string Id) : IQuery<Result<TicketDetailsDto>>;

Step 2: Enabling Scalar in Program.cs

Enable native endpoints in Program.cs:

// 1. Register native OpenAPI 3.1 generator
builder.Services.AddBitzOrcasOpenApiDocumentation(); // title from the OpenApi config section — wrapper, not bare AddOpenApi

var app = builder.Build();

// Enabled-ness is decided by OpenApiDocumentationOptions.IsEnabledFor(env) plus
// OpenApi:Enabled / OpenApi:RequireAuthentication — anonymous or cookie-gated.
// Modern layout and Nonce injection are fixed; no raw ScalarTheme.Moon knobs.
app.MapBitzOrcasOpenApiDocumentation();

The platform host listens on http://localhost:6881 (HTTPS 6883). In Development, open http://localhost:6881/scalar/v1 for the interactive API console with built-in request testing. Other environments require an explicit OpenApi:Enabled; with OpenApi:RequireAuthentication=true the docs are gated by a docs-session cookie, and the process refuses to start when the preview host lacks that setting.

Summary

OpenAPI + Scalar delivers top-tier developer ergonomics:

• Zero Reflection: Millisecond container cold starts;
• OpenAPI 3.1: Full support for rich schemas and polymorphic types;
• Scalar UI: Beautiful, interactive API debugging out of the box.