Crping.ApiDoc.Scalar 0.3.1

.NET 10.0 This package targets .NET 10.0. The package is compatible with this framework or higher. 
dotnet add package Crping.ApiDoc.Scalar --version 0.3.1
                    


                    

                
NuGet\Install-Package Crping.ApiDoc.Scalar -Version 0.3.1
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="Crping.ApiDoc.Scalar" Version="0.3.1" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="Crping.ApiDoc.Scalar" Version="0.3.1" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="Crping.ApiDoc.Scalar" />
                    


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add Crping.ApiDoc.Scalar --version 0.3.1
                    


                    

                
#r "nuget: Crping.ApiDoc.Scalar, 0.3.1"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#:package Crping.ApiDoc.Scalar@0.3.1
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package. 
#addin nuget:?package=Crping.ApiDoc.Scalar&version=0.3.1
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=Crping.ApiDoc.Scalar&version=0.3.1
                    


                            Install as a Cake Tool

Crping.ApiDoc.Scalar

基于 Scalar.AspNetCore 的 OpenAPI 文档扩展包,内置 JWT Bearer 安全方案 + 默认仅 IsDevelopment 暴露。

版本日志

0.3.1

2026-09-14
  • 修复:AddOpenApi 固定注册文档名 "v1"(无参重载默认),而 Scalar UI 按 options.DocumentName 拼 /openapi/{name}.json——消费者自定义 DocumentName(如 "v2")后 UI 指向不存在的文档 URL(404);文档名改与 UI 同源(均取 options.DocumentName,默认 v1 行为不变)

0.3.0

2026-07-15
  • 精简:移除三轨元数据(AssemblyDocMetadata + IConfiguration/Assembly 回退链),InfoTransformer 直接从 ApiDocOptions 读取
  • 精简:移除 GetLocalDevServer(自动检测本地监听地址),Development 环境不再自动注入 Local server
  • 保留核心功能:Bearer SecurityScheme / 环境暴露 / CORS / Persistent Authentication

0.2.0

2026-07-14
  • 重写为"API 文档最佳实践"形态
  • 新增 ApiDocOptions + 三轨元数据(配置 → 程序集 → 默认值)
  • 新增 InfoTransformer / BearerSecuritySchemeTransformer 拆分职责
  • 默认全局应用 Bearer SecurityRequirement(Scalar UI 锁定图标)
  • 默认仅 IsDevelopment 暴露;IsExposeInProduction opt-in
  • csproj 瘦身:删除 Microsoft.AspNetCore.Authentication.JwtBearer / Microsoft.Extensions.DependencyInjection* / Microsoft.IdentityModel.Tokens(全部 transitive)
  • 新增包元数据(Authors / Description / PackageReadmeFile / Version 0.2.0)
  • PackageOutputPath 改为 $(NUGET_PACKAGES),移除硬编码 E:\Codes\dotnet\nupkg

0.1.0

  • 初始版本(仅 OpenApiSecurityScheme + AllowAnonymous)

用法

// Program.cs

// 1. 鉴权(必须早于 AddScalarApiDoc —— transformer 通过 IAuthenticationSchemeProvider 探测 Bearer)
builder.Services.AddAuthPolicy<AdminAuthHandler, MemberAuthHandler, Member, Member>(builder.Configuration);

// 2. 文档服务(默认 Bearer SecurityScheme)
builder.Services.AddScalarApiDoc(opts =>
{
    // 可选覆盖
    // opts.Title = "我的 API";
    // opts.IsExposeInProduction = true;
});

var app = builder.Build();

// 3. 文档管道(必须在 MapControllers 之前,且在 UseAuthentication/UseAuthorization 之后)
app.UseScalarApiDoc(options =>
{
    options.AddServer("https://api.example.com", "Production");
});
app.MapControllers();
app.Run();

设计要点

关注点 实现
JWT Bearer 自动注册 OpenApiSecurityScheme { Type=Http, Scheme="bearer", BearerFormat="JWT" },Description 渲染自 Crping.AuthPolicy:Issuer / Crping.AuthPolicy:Audience
全局锁定图标 document.Security 顶层注入全局 OpenApiSecurityRequirement,Scalar UI 每个端点显示锁
环境暴露 默认仅 IsDevelopment 暴露;生产需 opts.IsExposeInProduction = true 显式 opt-in
OpenAPI 路径 /openapi/{documentName}.json;Scalar UI 默认 /scalar
多文档 opts.DocumentName 切换(默认 v1)

注意事项

  • 中间件顺序: 启用 CORS 时,UseCors 必须在 UseAuthentication/UseAuthorization 之前。推荐顺序: UseRouting → UseCors → UseAuthentication → UseAuthorization → UseScalarApiDoc → MapControllers
  • CORS 生产环境: 留空 CorsOrigins 时 AllowAnyOrigin 不含 Credentials;生产环境需显式指定 Origins 以启用 Credentials(如持久化 Token)
Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.3.1 141 9/14/2026
0.3.0 192 7/16/2026

0.3.0 · 详见 Readme.md