.NetCore使用Swagger,且使用自定义UI(Knife4jUI)

前言

Swagger大家都不陌生&＃xff0c;Swagger (OpenAPI) 是一个与编程语言无关的接口规范&＃xff0c;用于描述项目中的 REST API。它的出现主要是节约了开发人员编写接口文档的时间&＃xff0c;可以根据项目中的注释生成对应的可视化接口文档。

Swagger 的优势

• 支持 API 自动生成同步的在线文档&＃xff1a;使用 Swagger 后可以直接通过代码生成文档&＃xff0c;不再需要自己手动编写接口文档了&＃xff0c;对程序员来说非常方便&＃xff0c;可以节约写文档的时间去学习新技术。
• 提供 Web 页面在线测试 API&＃xff1a;光有文档还不够&＃xff0c;Swagger 生成的文档还支持在线测试。参数和格式都定好了&＃xff0c;直接在界面上输入参数对应的值即可在线测试接口。

使用 Swagger

1.再NuGet包管理器中搜索 “Swashbuckle.AspNetCore” 并且进行安装

2. 开启XML文档文件

注&＃xff1a;我使用的是VS2022 &＃xff0c; 其他版本可能不叫“文档文件”&＃xff0c; 应该是叫做“XML文档文件”

3. 运行项目即可

 4.加载注释

现在Swagger已经搭建完成&＃xff0c; 但是可以看到接口并没有注释&＃xff0c; 如果这个样子给前端的小姐姐用&＃xff0c; 估计会被吐槽死&＃xff0c; 接下来我们就需要配置注释。

再“Startup” 类的“ConfigureServices”方法改成如下所示&＃xff1a;

public void ConfigureServices(IServiceCollection services)
{services.AddControllers();services.AddSwaggerGen(c &＃61;>{c.SwaggerDoc("v1", new OpenApiInfo { Title &＃61; "Swagger", Version &＃61; "v1" });c.IncludeXmlComments(System.IO.Path.Combine(AppContext.BaseDirectory, "Swagger.xml"), true);});
}


然后重新运行就看可以看到对应的注释了

自定义UI(Knife4jUI)

Swagger 默认页面看起来太丑了&＃xff0c; 并且用起来也并不是那么友好&＃xff0c;想自己重新定义&＃xff0c;但是太麻烦了&＃xff0c; 于是在网上寻找了一番&＃xff0c;有人自定义了Swagger 的UI 页面&＃xff0c; 接下来看下如何使用吧。更多信息请看官网&＃xff1a;IGeekFan.AspNetCore.Knife4jUI

1.再NuGet包管理器中搜索 “IGeekFan.AspNetCore.Knife4jUI” 并且进行安装

 2. 加载自定义页面配置

//Swagger使用自定义UIapp.UseKnife4UI(c &＃61;>{c.RoutePrefix &＃61; string.Empty;c.SwaggerEndpoint($"/swagger/v1/swagger.json", "h.swagger.webapi v1");});


 完整的配置如下图

 如果不注释“app.UseSwaggerUI(c &＃61;> c.SwaggerEndpoint("/swagger/v1/swagger.json", "Swagger v1"));” &＃xff0c;就可以显示两个页面&＃xff0c;一个Swagger默认的&＃xff0c;另外一个是自定义的。

启动重新运行之后&＃xff0c;使用根路径访问&＃xff0c;就可以看到自定义的页面