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;
}