.NET Core配置Swagger

news/2024/12/31 1:58:58/

配置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文件启动程序即可。