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

 

一、什么是 Knife4j？

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

• • 接口分组展示
• • 接口排序
• • 离线文档导出
• • 接口调试支持
• • 更友好的中文界面支持

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

---

二、安装 Knife4jUI

1. 安装 NuGet 包

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

dotnet add package IGeekFan.AspNetCore.Knife4jUI 
dotnet add package Swashbuckle.AspNetCore

三、配置 Knife4jUI

1. 注册服务（Program.cs）

在 Program.cs 中注册 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();

 

⚠️ 注意：如果你之前用了 UseSwaggerUI()，请替换为 UseKnife4jUI()。

---

四、启用 XML 注释（可选）

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

1. 修改项目文件 .csproj

打开你的 .csproj 文件，添加以下内容：

<PropertyGroup>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

2. 配置 Swagger 注释路径（Program.cs）

builder.Services.AddSwaggerGen(options =>
{
    var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename));
});

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

/// <summary>
/// 天气服务
/// </summary>
[ApiController]
[Route("[controller]")]
publicclassWeatherForecastController : ControllerBase
{
    privatestaticreadonlystring[] Summaries = new[]
    {
        "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
    };
     
    /// <summary>
    /// 测试服务
    /// </summary>
    /// <returns></returns>
    [HttpGet(Name = "GetWeatherForecast")]
    public IEnumerable<WeatherForecast> Get()
    {
        return Enumerable.Range(1, 5).Select(index => new WeatherForecast
        {
            Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            TemperatureC = Random.Shared.Next(-20, 55),
            Summary = Summaries[Random.Shared.Next(Summaries.Length)]
        })
        .ToArray();
    }
}

 

---

五、访问 Knife4j UI 界面

启动项目后，在浏览器中访问：

http://localhost:<port>

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

 

---