AspNetCore 中使用 Knife4jUI 更加友好的Swagger界面

我会带着你远行 2024-04-23 20:23 61阅读 0赞

### ?介绍 ###

aspnetcore.knife4j是一个基于.NET Core平台的Swagger UI库，它提供了API文档的生成和管理功能。这个库的前身是swagger-bootstrap-ui，在Java项目中广泛使用，由于其优秀的界面和易用性被许多开发者所推崇。现在，aspnetcore.knife4j已经被集成到了.NET Core 3.0+和.NET Standard 2.0中。

通过使用aspnetcore.knife4j，开发者可以为自己的应用生成API文档，从而可以更方便地基于API文档进行测试。生成的文档还可以导出，然后提供给前端开发团队，前端开发团队可以根据这些API接口编写具体的调用代码。这不仅提高了开发效率，也有助于提高项目的可维护性和可读性。

此外，knife4j还提供了许多增强扩展功能，如自定义文档、动态参数调试、I18n、接口排序、导出等。

## ?案例 ##

?创建一个Asp.net Core 的webApi项目，debug启动，这是官方默认使用的swagger界面

![1dafd5f45d3741509eb45aae30fe8ab3.png][]

?首先，安装nuget包

Package Manager : 
    
    Install-Package Swashbuckle.AspNetCore.Swagger
    Install-Package Swashbuckle.AspNetCore.SwaggerGen
    Install-Package IGeekFan.AspNetCore.Knife4jUI
    
    OR
    
    CLI :
    
    dotnet add package Swashbuckle.AspNetCore.Swagger
    dotnet add package Swashbuckle.AspNetCore.SwaggerGen
    dotnet add package IGeekFan.AspNetCore.Knife4jUI

?因为创建的是webApi项目，已经自带了前两个包，因此只需要安装第三个

![13618b540202488fb73d6685b55fb3e3.png][]

?安装完成后在Program中找到原来的Swagger请求管道

将 app.UseSwaggerUI(); 换成以下代码

app.UseKnife4UI(p =>
        {
            p.SwaggerEndpoint("/swagger/v1/swagger.json", "测试");
            p.RoutePrefix = ""; // 路由前缀
        });

![d2f2c019b921430f85831b49e7dfa580.png][]

? 然后将 launchSettings.json 文件中的 "launchUrl" 值设置为空，这样当项目启动的时候，就会直接跳转到当前项目的applicationUrl

![8410a7824c5f465ca64f6bfcf8fe1698.png][]

?此时启动项目，swagger界面就是下面这样了

![08f391f07bc54e4382dfd3ad06125808.png][]

? 在Controller中添加一个测试接口

/// <summary>
    /// 测试控制器
    /// </summary>
    // [ApiController]
    [Route("[controller]/[action]")]
    public class TestController : ControllerBase
    {
        /// <summary>
        /// 测试
        /// </summary>
        /// <returns></returns>
        [HttpGet]
        public OkResult Test()
        {
            return Ok();
        }
    }

?在项目属性中勾选生成XML Documentation文档

![9cb6e4dbb8944d5e8d20fba835748896.png][]

或者

?编辑项目的.csproj文件，在文件中插入

<PropertyGroup Condition=" '$(Configuration)' == 'Debug' ">
          <DocumentationFile>bin\Debug\WebApplication.xml</DocumentationFile>
        </PropertyGroup>

这样在 Debug 模式下编译 .NET 项目时，指定生成一个名为 \*\*\*`.xml` 的 XML 文档文件，该文件包含了项目源代码中的文档注释 ,这些注释用于生成 API 文档或者提供 IntelliSense 功能时的描述信息。

![a6858556158641a381c4d9b2d2acc895.png][]

?此时重启项目，我们的接口功能描述信息就变成在项目中写的 ///注释 了

![b4c981c49d2840be85e195ae8ad46547.png][]

![00ee5a0bc4de495e9f6f83e193d64370.png][]

[1dafd5f45d3741509eb45aae30fe8ab3.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/23/420695b8debd404b8614debdaae52076.png
[13618b540202488fb73d6685b55fb3e3.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/23/09803e780af84d7988743550bbe1e895.png
[d2f2c019b921430f85831b49e7dfa580.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/23/4118d2d7a6db43a9a4243ceda1e42fdf.png
[8410a7824c5f465ca64f6bfcf8fe1698.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/23/8d7d5ac4e2b042bbbdd2fc222756013c.png
[08f391f07bc54e4382dfd3ad06125808.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/23/11cb52147327458382d1d1c487af8f45.png
[9cb6e4dbb8944d5e8d20fba835748896.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/23/74df2317a65944288dcd443e1d9a035c.png
[a6858556158641a381c4d9b2d2acc895.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/23/65ebaf4324784ee2a028156a359c848f.png
[b4c981c49d2840be85e195ae8ad46547.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/23/361e5d83be5e43689439eaae06fad716.png
[00ee5a0bc4de495e9f6f83e193d64370.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/23/387f7614444b44a29c67a8cb711442c8.png