//注册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));
// 注册 FreeSqlHelper
builder.Services.AddSingleton<FreeSqlHelper>();
// 注册 Swagger 服务
AddSwaggerService(builder.Services);
// 添加控制器支持(用于Web API)
builder.Services.AddControllers();
// 构建应用程序
var app = builder.Build();
// 启用Swagger和Swagger UI
ConfigSwagger(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 中间件。
运行后效果
- 访问
http://localhost:5000/doc
(或其他你配置的端口),你将看到 Swagger UI 页面,展示了所有 API 端点以及可用的操作。