.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文件,右击-“属性”-“复制到输出目录”设置为“始终复制”即可。
.netcore 3.1高性能微服务架构:加入swagger接口文档的更多相关文章
- .netcore 3.1高性能微服务架构:封装调用外部服务的接口方法--HttpClient客户端思路分析
众所周知,微服务架构是由一众微服务组成,项目中调用其他微服务接口更是常见的操作.为了便于调用外部接口,我们的常用思路一般都是封装一个外部接口的客户端,使用时候直接调用相应的方法.webservice或 ...
- .netcore 3.1高性能微服务架构:webapi规范
1.1 定义 1.基础接口:单一职责原则,每个接口只负责各自的业务,下接db,通用性强. 2.聚合接口:根据调用方需求聚合基础接口数据,业务性强. 1.2 协议 1. 客户端在通过 API 与后端服务 ...
- SpringCloud SpringBoot 前后端分离企业级微服务架构源码赠送
基于SpringBoot2.x.SpringCloud和SpringCloudAlibaba并采用前后端分离的企业级微服务敏捷开发系统架构.并引入组件化的思想实现高内聚低耦合,项目代码简洁注释丰富上手 ...
- swagger2 接口文档,整个微服务接口文档
1,因为整个微服务会有好多服务,比如会员服务,支付服务,订单服务,每个服务都集成了swagger 我们在访问的时候,不可能每个服务输入一个url 去访问,看起来很麻烦,所以我们需要在一个页面上集成整个 ...
- (1)学习笔记 ) ASP.NET CORE微服务 Micro-Service ---- 什么是微服务架构,.netCore微服务选型
开发工具:VS2017 .Net Core 2.1 什么是微服务?单体结构: 缺点: 1)只能采用同一种技术,很难用不同的语言或者语言不同版本开发不同模块: 2)系统耦合性强,一旦其中一个模块有问题, ...
- (1).NET CORE微服务 Micro-Service ---- 什么是微服务架构,.netCore微服务选型
开发工具:VS2017 .Net Core 2.1 什么是微服务?单体结构: 缺点:1)只能采用同一种技术,很难用不同的语言或者语言不同版本开发不同模块:2)系统耦合性强,一旦其中一个模块有问题,整个 ...
- 什么是微服务架构,.netCore微服务选型
什么是微服务架构,.netCore微服务选型 https://www.cnblogs.com/uglyman/p/9182485.html 开发工具:VS2017 .Net Core 2.1 什么是微 ...
- 腾讯开源微服务架构 Tars,高性能 RPC 开发框架
腾讯微服务架构 Tars 于今日正式开源. Tars 取名于电影“星际穿越”中的机器人,是支持多语言的高性能 RPC 开发框架和配套一体化的服务治理平台,可以帮助企业或者用户以微服务的方式快速构建稳定 ...
- 庐山真面目之八微服务架构 NetCore 基于 Dockerfile 文件部署
庐山真面目之八微服务架构 NetCore 基于 Dockerfile 文件部署 一.简介 从今天开始,不出意外的话,以后所写的文章中所介绍项目的部署环境都应该会迁移到Linux环境上,而且是 ...
随机推荐
- TampeMonkey 关于 youtube的两个插件
一个是 Video Speed Buttons 负责调速 一个是 YouTube Links 负责下载不同分辨率的视频
- 【01】HTML_day01_01-前言&WEB标准
typora-copy-images-to: media 第01阶段.前端基础.认识WEB 基础班学习目标 目标: 能根据psd文件,用HTML+CSS 布局出符合W3C规范的网页. 网站首页 列表页 ...
- 查看mysql是否锁表了
1.查看表是否被锁: (1)直接在mysql命令行执行:show engine innodb status\G. (2)查看造成死锁的sql语句,分析索引情况,然后优化sql. (3)然后show p ...
- jQuery XSS漏洞
漏洞成因: jQuery中过滤用户输入数据所使用的正则表达式存在缺陷,可能导致location.hash跨站脚本攻击. 演示程序: <!DOCTYPE html> <html lan ...
- 【daily】Java枚举 - fastjson对enum的处理
目的 1.枚举值转换成完全的json: 2.对象中的枚举成员完全转换成json: 3.枚举类的全部值转换成json: 枚举定义 public enum SongsEnum { SAFE_AND_SOU ...
- 剑指offer-面试题53_2-0~n-1中缺失的数字-二分查找
/* 题目: 寻找递增数组0~n-1中缺失的数字. */ /* 思路: 变形二分法. */ #include<iostream> #include<cstring> #incl ...
- python 访问sql server数据库
访问数据库 cnxn = pyodbc.connect("Driver={SQL Server};Server=localhost;Database=用户名;uid=sa;pwd=密码&qu ...
- 【剑指Offer】05、用两个栈实现队列
题目描述 用两个栈来实现一个队列,完成队列的Push和Pop操作. 队列中的元素为int类型. 题解一: //stack2有元素就pop,没有元素就将stack1中所有元素倒进来再pop public ...
- Uva12716 素数筛思想的应用
Uva12716 题意: 输入整数n,1<= n <=3e7,问有多少个整数对(a,b)满足:1 <= b <= a <= n,且gcd(a,b)== a XOR b 解 ...
- TCP 协议快被淘汰了,UDP 协议才是新世代的未来?
TCP 协议可以说是今天互联网的基石,作为可靠的传输协议,在今天几乎所有的数据都会通过 TCP 协议传输,然而 TCP 在设计之初没有考虑到现今复杂的网络环境,当你在地铁上或者火车上被断断续续的网络折 ...