.netcore 3.1高性能微服务架构：加入swagger接口文档

本文为原创文章：首发：http://www.zyiz.net/tech/detail-108663.html

swagger是什么？

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

swagger作用

(1)接口的文档在线自动生成。 
  (2)功能测试。

接口开发的痛点

相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范大家是不够的，随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了。
 
但即便如此，对于许多开发来说，编写这个yml或json格式的描述文件，本身也是有一定负担的工作，特别是在后面持续迭代开发的时候，往往会忽略更新这个描述文件，直接更改代码。久而久之，这个描述文件也和实际项目渐行渐远，基于该描述文件生成的接口文档也失去了参考意义。所以再Java届服务端的大一统框架Spring，迅速将Swagger规范纳入自身的标准，建立了Spring-swagger项目，后面改成了现在的Springfox。通过在项目中引入Springfox，可以扫描相关的代码，生成该描述文件，进而生成与代码一致的接口文档和客户端代码。而.Net生态，自从webapi2.0开始便开始使用Swagger作为接口文档，到.NetCore生化后，Swagger更是普通使用的接口文档规范，最常使用的组件就是Swashbuckle.AspNetCore。
这种通过代码生成接口文档的形式，在后面需求持续迭代的项目中，显得尤为重要和高效。

.NetCore3.1中如何使用Swagger呢？

第一步：引入Swagger

用Vs2019创建.NetCore3.1的WebApi项目后，在VS2019里依次点击  “工具”-“NuGet包管理器(N)”-"管理解决方案的NuGet程序包(N)",打开后，搜索“Swashbuckle.AspNetCore”，选择最新版（目前最新版本为5.0.0），解决方案的项目列表里勾选WebApi项目，其他的项目（比如Domain,Common,Infrastructure）不需要勾选。点击“安装即可”。

第二步：Startup配置

1、ConfigureServices方法里将Swagger加入到容器IServiceCollection里，，并且指定读取站点目录下所有的xml文件，代码如下：

 services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new OpenApiInfo { Version = "v1", Title = "zyiz.net系统WebApi" });
                  
                var dir = new DirectoryInfo(AppContext.BaseDirectory);
                foreach (FileInfo file in dir.EnumerateFiles("*.xml"))
                {
                    c.IncludeXmlComments(file.FullName);
                }
            });

 

2、Configure方法里开启SwaggerUI，代码如下：

app.UseSwagger().UseSwaggerUI(c => { c.SwaggerEndpoint("/swagger/v1/swagger.json", "Zyiz.net API V1"); });

第三步：设置并且生成xml文件

1、解决方案-WebApi项目名右击---“属性”，点“生成”，界面下方，“输出”部分，勾选“XML文档文件(X)”,可以看到生成的路径为绝对路径，可以改为相对路径，类似这样，加2个点好，然后是WebApi项目目录名，后面的xml文件名不变。

..\MuXue.Zyiz.Template.WebApi\MuXue.Zyiz.Template.WebApi.xml

2、项目一般会有Model的实体层，配置跟上面类似，

..\MuXue.Zyiz.Template.WebApi\MuXue.Zyiz.Template.WebApi.xml

 

第4步：生成解决方案，F5启动即可。

有人发现，本地的swagger有字段说明，但是发布到服务器上，就没有字段说明，原因是.netcore 3.1发布后，不会生成xml文件。解决方方法是，在vs2019项目里，刚刚我们设置成功生成的2个xml文件，右击-“属性”-“复制到输出目录”设置为“始终复制”即可。