.netcore 3.1高性能微服务架构:加入swagger接口文档
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。
wagger作用
(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文件,代码如下:
1 2 3 4 5 6 7 8 9 10 |
|
2、Configure方法里开启SwaggerUI,代码如下:
1 |
|
第三步:设置并且生成xml文件
1、解决方案-WebApi项目名右击---“属性”,点“生成”,界面下方,“输出”部分,勾选“XML文档文件(X)”,可以看到生成的路径为绝对路径,可以改为相对路径,类似这样,加2个点好,然后是WebApi项目目录名,后面的xml文件名不变。
1 |
|
2、项目一般会有Model的实体层,配置跟上面类似,
1 |
|
第4步:生成解决方案,F5启动即可。
有人发现,本地的swagger有字段说明,但是发布到服务器上,就没有字段说明,原因是.netcore 3.1发布后,不会生成xml文件。解决方方法是,在vs2019项目里,刚刚我们设置成功生成的2个xml文件,右击-“属性”-“复制到输出目录”设置为“始终复制”即可。