当前位置：首页 > news >正文

配置更加美观的 Swagger UI

news 2025/6/28 5:06:07

//注册Swagger服务
private static void AddSwaggerService(IServiceCollection services){services.AddSwaggerGen(opt =>{opt.SwaggerDoc("Push", new OpenApiInfo{Version = "v1",Title = "Push API",Description = "Push API 文档",Contact = new OpenApiContact() { Name = "Yc" }});// 加载 XML 文档注释（如果有）var files = Directory.GetFiles(AppContext.BaseDirectory, "*.xml", SearchOption.TopDirectoryOnly);foreach (var file in files){opt.IncludeXmlComments(file, true);}});}// 启用Swagger和Swagger UI
private static void ConfigSwagger(IApplicationBuilder app, IWebHostEnvironment env){app.UseSwagger(opt => opt.RouteTemplate = "doc/swagger/{documentName}/swagger.json");app.UseKnife4UI(option =>{option.RoutePrefix = "doc";option.DocumentTitle = "Push API";option.SwaggerEndpoint("/doc/swagger/Push/swagger.json", "Push Docs");});}//完整Program.cs示例
internal class Program{static void Main(string[] args){var builder = WebApplication.CreateBuilder(args);/// <summary>/// 配置跨域/// </summary>builder.Services.AddCors(options =>{options.AddPolicy("Cors", policy =>{policy.AllowAnyHeader().AllowAnyOrigin().AllowAnyMethod();});});// 配置应用程序监听所有 IP 地址上的端口builder.WebHost.UseUrls("http://0.0.0.0:5000");// 配置 Kestrel 服务器以监听所有 IP 地址builder.WebHost.ConfigureKestrel(serverOptions =>{serverOptions.ListenAnyIP(5000); // 监听端口 5000 上的所有 IP 地址serverOptions.ListenAnyIP(0); // 0 表示由操作系统动态分配端口});// 配置应用程序配置builder.Configuration.SetBasePath(Directory.GetCurrentDirectory());builder.Configuration.AddJsonFile("appsettings.json", optional: true, reloadOnChange: true);// 将配置绑定到 PushETOptions 实例builder.Services.Configure<PushETOptions>(builder.Configuration.GetSection(PushETOptions.ConfigKey));// 注册 FreeSqlHelperbuilder.Services.AddSingleton<FreeSqlHelper>();// 注册 Swagger 服务AddSwaggerService(builder.Services);// 添加控制器支持（用于Web API）builder.Services.AddControllers();// 构建应用程序var app = builder.Build();// 启用Swagger和Swagger UIConfigSwagger(app, app.Environment);// 配置中间件管道if (app.Environment.IsDevelopment()){app.UseDeveloperExceptionPage(); // 开发环境下显示详细错误页面}app.UseRouting();app.UseEndpoints(endpoints =>{endpoints.MapControllers(); // 映射控制器路由});// 运行应用程序app.Run();}private static void AddSwaggerService(IServiceCollection services){services.AddSwaggerGen(opt =>{opt.SwaggerDoc("Push", new OpenApiInfo{Version = "v1",Title = "Push API",Description = "Push API 文档",Contact = new OpenApiContact() { Name = "Yc" }});// 加载 XML 文档注释var files = Directory.GetFiles(AppContext.BaseDirectory, "*.xml", SearchOption.TopDirectoryOnly);foreach (var file in files){opt.IncludeXmlComments(file, true);}});}private static void ConfigSwagger(IApplicationBuilder app, IWebHostEnvironment env){app.UseSwagger(opt => opt.RouteTemplate = "doc/swagger/{documentName}/swagger.json");app.UseKnife4UI(option =>{option.RoutePrefix = "doc";option.DocumentTitle = "Push API";option.SwaggerEndpoint("/doc/swagger/Push/swagger.json", "Push Docs");});}}

AddSwaggerService 方法：
- 此方法注册 Swagger 服务，并配置 Swagger 文档信息、安全定义（如 Bearer Token），以及其他 Swagger 相关设置。
- opt.IncludeXmlComments(file, true); 使 Swagger 使用 XML 文档注释来生成更详细的 API 文档。
ConfigSwagger 方法：
- 此方法配置了 Swagger 和 Swagger UI 的中间件，使得你可以通过 /doc 路径访问生成的 API 文档页面。
- 使用 UseKnife4UI 是为了提供一个更加美观的 Swagger UI；如果报错请添加对应Nuget包；
  using IGeekFan.AspNetCore.Knife4jUI;
Main 方法中的调用：
- 在 Main 方法中，你首先调用 AddSwaggerService(builder.Services) 来注册 Swagger 服务，然后在 app 构建之后，调用 ConfigSwagger(app, app.Environment) 来配置 Swagger 中间件。