using Microsoft.OpenApi; using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.Configuration; using Microsoft.AspNetCore.Builder; namespace KH.WMS.Core.Api.Documentation.Swagger; /// /// Swagger 配置 /// public static class SwaggerSetup { /// /// 添加 Swagger 服务 /// public static IServiceCollection AddSwaggerDocumentation(this IServiceCollection services, IConfiguration configuration) { var swaggerOptions = configuration.GetSection("Swagger").Get(); swaggerOptions ??= new SwaggerOptions(); services.AddSwaggerGen(options => { var info = new OpenApiInfo { Title = swaggerOptions.Title, Version = swaggerOptions.Version, Description = swaggerOptions.Description }; // 只有在 URL 不为空时才设置 Contact if (!string.IsNullOrWhiteSpace(swaggerOptions.ContactName) || !string.IsNullOrWhiteSpace(swaggerOptions.ContactEmail) || !string.IsNullOrWhiteSpace(swaggerOptions.ContactUrl)) { info.Contact = new OpenApiContact { Name = swaggerOptions.ContactName, Email = swaggerOptions.ContactEmail }; if (!string.IsNullOrWhiteSpace(swaggerOptions.ContactUrl)) { info.Contact.Url = new Uri(swaggerOptions.ContactUrl); } } // 只有在 URL 不为空时才设置 License if (!string.IsNullOrWhiteSpace(swaggerOptions.LicenseName) || !string.IsNullOrWhiteSpace(swaggerOptions.LicenseUrl)) { info.License = new OpenApiLicense { Name = swaggerOptions.LicenseName }; if (!string.IsNullOrWhiteSpace(swaggerOptions.LicenseUrl)) { info.License.Url = new Uri(swaggerOptions.LicenseUrl); } } options.SwaggerDoc(swaggerOptions.Version, info); // 添加 JWT 认证 if (swaggerOptions.EnableJwt) { options.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme { Description = "JWT 授权令牌,请在下方输入框中输入 Bearer {token}(注意两者之间有一个空格)", Name = "Authorization", In = ParameterLocation.Header, Type = SecuritySchemeType.ApiKey, Scheme = "Bearer" }); options.AddSecurityRequirement(document => new OpenApiSecurityRequirement { [new OpenApiSecuritySchemeReference("Bearer")] = new List() }); } }); return services; } /// /// 使用 Swagger 中间件 /// public static IApplicationBuilder UseSwaggerDocumentation(this IApplicationBuilder app, IConfiguration configuration) { var swaggerOptions = configuration.GetSection("Swagger").Get(); swaggerOptions ??= new SwaggerOptions(); app.UseSwagger(); app.UseSwaggerUI(options => { options.SwaggerEndpoint($"/swagger/{swaggerOptions.Version}/swagger.json", $"{swaggerOptions.Title} {swaggerOptions.Version}"); options.RoutePrefix = swaggerOptions.RoutePrefix; options.DocumentTitle = swaggerOptions.Title; options.DefaultModelsExpandDepth(-1); // 隐藏模型 }); return app; } } /// /// Swagger 配置选项 /// public class SwaggerOptions { /// /// 标题 /// public string Title { get; set; } = "API Documentation"; /// /// 版本 /// public string Version { get; set; } = "v1"; /// /// 描述 /// public string Description { get; set; } = "API Documentation"; /// /// 联系人名称 /// public string ContactName { get; set; } = ""; /// /// 联系人邮箱 /// public string ContactEmail { get; set; } = ""; /// /// 联系人URL /// public string ContactUrl { get; set; } = ""; /// /// 许可证名称 /// public string LicenseName { get; set; } = ""; /// /// 许可证URL /// public string LicenseUrl { get; set; } = ""; /// /// 路由前缀 /// public string RoutePrefix { get; set; } = "swagger"; /// /// 是否启用 JWT 认证 /// public bool EnableJwt { get; set; } = true; }