API 文档也能这么好看？ASP.NET Core 集成 Knife4j

摘要：在中注册 Knife4j 和 Swagger 服务：var builder = WebApplication.CreateBuilder(args);// 添加 Swagger 服务 Knife4j UIbuilder.Services.AddSwaggerG

Knife4j 是一个基于 Swagger 的 API 文档增强工具，它在原生的 Swagger UI 基础上提供了更美观的界面和更多实用功能，如：

• 接口分组展示

• 接口排序

• 离线文档导出

• 接口调试支持

• 更友好的中文界面支持

IGeekFan.AspNetCore.Knife4jUI是为 ASP.NET Core 平台封装的 Knife4j UI 组件包，可以轻松替代默认的 Swagger UI 页面。1. 安装 NuGet 包

需要安装 Swashbuckle.AspNetCore 来生成 Swagger JSON

dotnet add package IGeekFan.AspNetCore.Knife4jUI
dotnet add package Swashbuckle.AspNetCore在中注册 Knife4j 和 Swagger 服务：var builder = WebApplication.CreateBuilder(args);

// 添加 Swagger 服务 Knife4j UI
builder.Services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo { Title = "API V1", Version = "v1" });
c.AddServer(new OpenApiServer
{
Url = "",
Description = "vvv"
});
c.CustomOperationIds(apiDesc =>
{
var controllerAction = apiDesc.ActionDescriptor as ControllerActionDescriptor;
return controllerAction.ControllerName + "-" + controllerAction.ActionName;
});
});

var app = builder.Build;

// 启用中间件
if (app.Environment.IsDevelopment)
{
app.UseSwagger;

//app.UseSwaggerUI;
app.UseKnife4UI(c =>
{
c.RoutePrefix = ""; // serve the UI at root --knife4j
c.SwaggerEndpoint("/swagger/v1/swagger.json", "V1 Docs");
});
}

app.MapControllers;

app.Run;⚠️ 注意：如果你之前用了，请替换为

为了让 Knife4j 显示接口注释信息，你需要启用 XML 注释。

1. 修改项目文件 .csproj打开你的.csproj文件，添加以下内容：PropertyGroup
GenerateDocumentationFile>true
NoWarn>$(NoWarn);1591NoWarn
PropertyGroup2. 配置 Swagger 注释路径（Program.cs）builder.Services.AddSwaggerGen(options =>
{
var xmlFilename = $"{Assembly.GetExecutingAssembly.GetName.Name}.xml";
options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename));
});

确保控制器和方法都加上了 XML 注释：

///
/// 天气服务
///
[ApiController]
[Route("[controller]")]
publicclassWeatherForecastController:ControllerBase
{
privatestaticreadonlystring Summaries = new
{
"Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

///
/// 测试服务
///
///
[HttpGet(Name = "GetWeatherForecast")]
public IEnumerableGet
{
return Enumerable.Range(15).Select(index => new WeatherForecast
{
Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
TemperatureC = Random.Shared.Next(-2055),
Summary = Summaries[Random.Shared.Next(Summaries.Length)]
})
.ToArray;
}
}

你将看到 Knife4j 提供的增强版 API 文档界面。