.NET Core配置Swagger

配置Swagger主要方便测试接口

无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范大家是不够的，随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了。发现了痛点就要去找解决方案，解决方案用的人多了，就成了标准的规范，这就是Swagger。

1.创建.NET Core API 项目

我用的开发工具是Visual Studio 2022，选择如下模板创建即可。

2.安装Swashbuckle.AspNetCore包

打开NuGet界面，搜索Swashbuckle.AspNetCore，安装即可。

3.添加Swaggers文件

Swaggers文件下载链接
提取码：2g9d

将下载的文件放到根目录，如下所示：

4.修改Program.cs文件

新建的.NET Core API 项目中Program.cs如下：

修改builder.Services.AddSwaggerGen();如下：

builder.Services.AddSwaggerGen(c =>
{
	c.SwaggerDoc("1.0", new OpenApiInfo
	{
		Version = "1.0",
		Title = "WebApplication1 接口文档",
		Description = "Documents for WebApplication1，用于三方接口调用",
		Contact = new OpenApiContact { Name = "测试", Email = "ceshi@qq.com" }
	});
	c.SwaggerDoc("cs", new Info { Title = "测试接口v1.0", Version = "1.0" });
	c.DocInclusionPredicate((docName, apiDes) =>
	{
		if (!apiDes.TryGetMethodInfo(out MethodInfo method))
			return false;
		/*使用ApiExplorerSettingsAttribute里面的GroupName进行特性标识
		 * DeclaringType只能获取controller上的特性
		 * 我们这里是想以action的特性为主
		 * */
		var version = method.DeclaringType.GetCustomAttributes(true).OfType<ApiExplorerSettingsAttribute>().Select(m => m.GroupName);
		if (docName == "v1" && !version.Any())
			return true;
		//这里获取action的特性
		var actionVersion = method.GetCustomAttributes(true).OfType<ApiExplorerSettingsAttribute>().Select(m => m.GroupName);
		if (actionVersion.Any())
			return actionVersion.Any(v => v == docName);
		return version.Any(v => v == docName);
	});

    c.IgnoreObsoleteProperties();
	c.IgnoreObsoleteActions();
	c.DocumentFilter<HiddenApiFilter>();
});

修改app.UseSwaggerUI();如下：

app.UseSwaggerUI(c =>
{
	c.ShowExtensions();
	c.SwaggerEndpoint("/swagger/cs/swagger.json", "测试接口v1.0");
});

5.编写接口

打开控制器，[HttpGet(Name = "")]定义接口名，[ApiExplorerSettings(GroupName = "")]定义接口组

6.运行

项目启动如下所示，点击Try it out即可测试，Parameters即入参，Responses即出参。

7.发布

打开程序包管理控制台，发布命令如下（项目正在运行无法发布）：

dotnet publish -o release

运行命令后会生成一个release文件夹。

打开release文件夹下的exe文件启动程序即可。