传统的 Swagger / Swashbuckle 在 .NET 现代企业架构中面临两大硬伤：

启动性能断崖式下跌：在服务启动时通过昂贵的运行时反射扫描上千个控制器和 DTO，导致冷启动耗时增加数秒；
Native AOT 严重不兼容：反射扫描在 AOT 裁剪模式下极易丢失关键类型元数据，引发运行时崩溃。

BitzOrcas.Modern 采用 .NET 10 原生 Microsoft.AspNetCore.OpenApi + Scalar 现代交互客户端：所有端点元数据由 [GenerateEndpoint] 在编译期提取，启动 0 反射，呈现极致丝滑的现代化 API 调试界面。

编译期 OpenAPI 提取与 Scalar 渲染

第一步：声明式端点契约

只需要在 Command 或 Query 上标注 [GenerateEndpoint]：

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

namespace BitzOrcas.Ticket.Application.Queries;

// 1. 声明式端点契约：由 Source Generator 在编译期自动提取 OpenAPI 元数据
// 2. 自动生成 Minimal API 端点与 Scalar 调试界面映射
[GenerateEndpoint(HttpRoute.Get, "/api/tickets/{id}", Tag = "Tickets")]
public sealed record GetTicketByIdQuery(string Id) : IQuery<Result<TicketDetailsDto>>;

第二步：在 Host 中启用 Scalar 交互式客户端

在 Program.cs 中开启标准端点映射：

// 1. 注册原生 OpenAPI 3.1 文档生成器
builder.Services.AddBitzOrcasOpenApiDocumentation(); // 标题来自 OpenApi 配置节；框架包装而非裸 AddOpenApi

var app = builder.Build();

// 是否启用由 OpenApiDocumentationOptions.IsEnabledFor(env) 与 OpenApi:Enabled /
// OpenApi:RequireAuthentication 决定，可匿名开放或以文档会话 Cookie 把门；
// 固定 Modern 布局并注入 Nonce，不使用 ScalarTheme.Moon 这类裸参数。
app.MapBitzOrcasOpenApiDocumentation();

平台宿主监听 http://localhost:6881（HTTPS 6883）。Development 环境访问 http://localhost:6881/scalar/v1 即可打开自带请求测试的 API 控制台；其他环境由 OpenApi:Enabled 显式打开，OpenApi:RequireAuthentication=true 时以文档会话 Cookie 把门，未配置时进程拒绝启动。

总结

OpenAPI + Scalar 为 BitzOrcas 提供了顶尖的 API 交互体验：

AOT 零反射：毫秒级极速冷启动；
OpenAPI 3.1 完整规范：支持复杂 Schema 与强类型枚举；
现代化 Scalar UI：颜值高、响应快、自带丰富代码生成片段。