大家好，我是MapMonkey。今天给大家分享一个强大的API文档工具-Swagger。
1、概述
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。其作用主要是 1. 接口的文档在线自动生成；2. 接口功能测试。
网管地址：https://swagger.io/
官网截图
Swagger官网主要提供了几种开源工具：
- Swagger Codegen: 通过Codegen 可以将描述文件生成html格式和cwiki形式的接口文档，同时也能生成多钟语言的服务端和客户端的代码。支持通过jar包，docker，node等方式在本地化执行生成。也可以在后面的Swagger Editor中在线生成。
- Swagger UI:提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目。
- Swagger Editor: 类似于markendown编辑器的编辑Swagger描述文件的编辑器，该编辑支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。
- Swagger Inspector: 感觉和postman差不多，是一个可以对接口进行测试的在线版的postman。比在Swagger UI里面做接口请求，会返回更多的信息，也会保存你请求的实际请求参数等数据。
- Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。
2、ASP.NET Core后台交互
-
环境VS2019
image.png
-
创建项目
选择创建新项目，下一步ASP.NET Core Web应用程序，选择相应的文件路径，选择Core版本**API项目，开始创建。
image.png
Controllers右击添加控制器,此处添加一个默认的控制器
image.png
运行程序，在浏览器输入[https://localhost:44322/api/default](根据自己的地址进行输入),如下图所示：
image.png
3、Swagger工具集成
-
安装程序包
【项目】—【管理NuGet程序包】—【浏览】中搜索“swagger”，安装前三个
image.png
-
配置Startup.cs文件
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo { Title = "API 接口", Version = "v1" });
});
image.png
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});
image.png
-
运行程序，在浏览器输入，如下图所示即表示成功https://localhost:44322/swagger/index.html
image.png
-
启用XML注释
右键单击“解决方案资源管理器”中的项目，然后选择“属性”
查看“生成”选项卡的“输出”部分下的“XML 文档文件”框
image.png
-
配置Startup.cs文件
//Locate the XML file being generated by ASP.NET...
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.XML";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);\
//... and tell Swagger to use those XML comments.
c.IncludeXmlComments(xmlPath);
image.png
-
代码中添加注释
image.png
-
运行程序，查看结果
image.png
参考文献：https://docs.microsoft.com/zh-cn/aspnet/core/web-api/?view=aspnetcore-3.1
