Crping.ApiDoc.NSwag 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.NSwag --version 0.3.1
                    


                    

                
NuGet\Install-Package Crping.ApiDoc.NSwag -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.NSwag" 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.NSwag" Version="0.3.1" />
                    


                            Directory.Packages.props
                        

                    

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


                            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.NSwag --version 0.3.1
                    


                    

                
#r "nuget: Crping.ApiDoc.NSwag, 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.NSwag@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.NSwag&version=0.3.1
                    


                            Install as a Cake Addin
                        

                    

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


                            Install as a Cake Tool

Crping.ApiDoc.NSwag

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

版本日志

0.3.1

2026-09-14
  • 加固:AddNSwagApiDoc 注册期的临时 ServiceProvider(ASP0000 BuildServiceProvider)改 using 及早释放,消除 builder 单例泄漏进主容器;jwtInfo 注册期固化维持既定取舍(NSwag 14.x SecurityDefinitionAppender 无 IServiceProvider 工厂重载,且 JWT 描述来自静态配置段)

0.3.0

2026-07-16
  • 新增 ApiDocOptions 配置类(Title / Description / Version / IsExposeInProduction / ExposePath / EnableCors 等)
  • 新增 JwtDocInfo:从 Crping.AuthPolicy 配置段读取 Issuer / Audience,渲染到 SecurityScheme 描述
  • 环境保护:默认仅 IsDevelopment 暴露;生产需 opts.IsExposeInProduction = true 显式 opt-in
  • 新增 CORS 支持(EnableCors + CorsOrigins)
  • AddNSwagApiDoc / UseNSwagApiDoc 返回值改为链式调用
  • 参数校验:ArgumentNullException.ThrowIfNull
  • csproj:PackageOutputPath 改为 $(NUGET_PACKAGES) 环境变量,移除硬编码路径
  • 新增 Usings.cs 全局 using
  • 移除无用 #region
  • 更新 Readme.md

0.2.0

2026-07-14
  • 显式声明 Microsoft.AspNetCore.App 共享框架引用
  • 移除冗余的 Microsoft.AspNetCore.OpenApi 包引用
  • 清理未使用的命名空间引用

0.1.0

2026-01-09
  • 初始版本发布

用法

// Program.cs

// 1. 鉴权(必须早于 AddNSwagApiDoc)
builder.Services.AddAuthPolicy<AdminAuthHandler, MemberAuthHandler, Member, Member>(builder.Configuration);

// 2. 文档服务(默认仅 Development 暴露)
builder.Services.AddNSwagApiDoc(opts =>
{
    // 可选覆盖
    // opts.Title = "我的 API";
    // opts.IsExposeInProduction = true;
    // opts.EnableCors = true;
});

var app = builder.Build();

// 3. 文档管道(必须在 MapControllers 之前,且在 UseAuthentication/UseAuthorization 之后)
app.UseNSwagApiDoc();
app.MapControllers();
app.Run();

设计要点

关注点 实现
JWT Bearer 自动注册 OpenApiSecurityScheme { Type=Http, Scheme="bearer", BearerFormat="JWT" },Description 渲染自 Crping.AuthPolicy:Issuer / Crping.AuthPolicy:Audience
环境暴露 默认仅 IsDevelopment 暴露;生产需 opts.IsExposeInProduction = true 显式 opt-in
OpenAPI 路径 /swagger/{documentName}/swagger.json;Swagger UI 默认 /swagger
多文档 opts.DocumentName 切换(默认 v1)
CORS opts.EnableCors = true 启用;留空 CorsOrigins 时 AllowAnyOrigin 不含 Credentials

注意事项

  • 中间件顺序: 推荐顺序: UseRouting → UseCors → UseAuthentication → UseAuthorization → UseNSwagApiDoc → MapControllers
  • CORS 生产环境: 留空 CorsOrigins 时 AllowAnyOrigin 不含 Credentials;生产环境需显式指定 Origins 以启用 Credentials
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 167 9/14/2026
0.3.0 245 7/16/2026
0.1.0 143 1/9/2026

0.3.0 · 详见 Readme.md