using NCC.ConfigurableOptions; using NCC.Reflection; using Microsoft.Extensions.Configuration; using Microsoft.OpenApi.Models; using Swashbuckle.AspNetCore.SwaggerUI; using System; using System.Linq; namespace NCC.SpecificationDocument { /// /// 规范化文档配置选项 /// public sealed class SpecificationDocumentSettingsOptions : IConfigurableOptions { /// /// 文档标题 /// public string DocumentTitle { get; set; } /// /// 默认分组名 /// public string DefaultGroupName { get; set; } /// /// 启用授权支持 /// public bool? EnableAuthorized { get; set; } /// /// 格式化为V2版本 /// public bool? FormatAsV2 { get; set; } /// /// 配置规范化文档地址 /// public string RoutePrefix { get; set; } /// /// 文档展开设置 /// public DocExpansion? DocExpansionState { get; set; } /// /// XML 描述文件 /// public string[] XmlComments { get; set; } /// /// 分组信息 /// public SpecificationOpenApiInfo[] GroupOpenApiInfos { get; set; } /// /// 安全定义 /// public SpecificationOpenApiSecurityScheme[] SecurityDefinitions { get; set; } /// /// 配置 Servers /// public OpenApiServer[] Servers { get; set; } /// /// 隐藏 Servers /// public bool? HideServers { get; set; } /// /// 默认 swagger.json 路由模板 /// public string RouteTemplate { get; set; } /// /// 配置安装第三方包的分组名 /// public string[] PackagesGroups { get; set; } /// /// 启用枚举 Schema 筛选器 /// public bool? EnableEnumSchemaFilter { get; set; } /// /// 启用标签排序筛选器 /// public bool? EnableTagsOrderDocumentFilter { get; set; } /// /// 后期配置 /// /// /// public void PostConfigure(SpecificationDocumentSettingsOptions options, IConfiguration configuration) { options.DocumentTitle ??= "Specification Api Document"; options.DefaultGroupName ??= "Default"; options.FormatAsV2 ??= false; //options.RoutePrefix ??= "api"; // 可以通过 UseInject() 配置,所以注释 options.DocExpansionState ??= DocExpansion.List; // 加载项目注册和模块化/插件注释 var frameworkPackageName = Reflect.GetAssemblyName(GetType()); var projectXmlComments = App.Assemblies.Where(u => u.GetName().Name != frameworkPackageName).Select(t => t.GetName().Name); var externalXmlComments = App.ExternalAssemblies.Any() ? App.Settings.ExternalAssemblies.Select(u => u.EndsWith(".dll") ? u[0..^4] : u) : Array.Empty(); XmlComments ??= projectXmlComments.Concat(externalXmlComments).ToArray(); GroupOpenApiInfos ??= new SpecificationOpenApiInfo[] { new SpecificationOpenApiInfo() { Group=options.DefaultGroupName } }; EnableAuthorized ??= true; if (EnableAuthorized == true) { SecurityDefinitions ??= new SpecificationOpenApiSecurityScheme[] { new SpecificationOpenApiSecurityScheme { Id="Bearer", Type= SecuritySchemeType.Http, Name="Authorization", Description="JWT Authorization header using the Bearer scheme.", BearerFormat="JWT", Scheme="bearer", In= ParameterLocation.Header, Requirement=new SpecificationOpenApiSecurityRequirementItem { Scheme=new OpenApiSecurityScheme { Reference=new OpenApiReference { Id="Bearer", Type= ReferenceType.SecurityScheme } }, Accesses=Array.Empty() } } }; } Servers ??= Array.Empty(); HideServers ??= true; RouteTemplate ??= "swagger/{documentName}/swagger.json"; PackagesGroups ??= Array.Empty(); EnableEnumSchemaFilter ??= true; EnableTagsOrderDocumentFilter ??= true; } } }