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

原创 管理员 2020/2/22 16:04:50

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


swagger是什么?


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

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)不需要勾选。点击“安装即可”。
111-001.png


111-2.png

第二步: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", "MuXue.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.Domain\MuXue.Zyiz.Template.Domain.xml


第4步:生成解决方案,F5启动即可。



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



随时随地学软件编程-关注百度小程序和微信小程序
关于找一找教程网

本站文章仅代表作者观点,不代表本站立场,所有文章非营利性免费分享。
本站提供了软件编程、网站开发技术、服务器运维、人工智能等等IT技术文章,希望广大程序员努力学习,让我们用科技改变世界。
[.netcore 3.1高性能微服务架构:加入swagger接口文档]http://www.zyiz.net/tech/detail-108663.html

上一篇:在.NET Core中使用MachineKey

下一篇:浏览器中的 .Net Core —— Blazor WebAssembly 初体验

赞(0)

共有 条评论 网友评论

验证码: 看不清楚?
    扫一扫关注最新编程教程