本文为原创文章:首发: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接口文档的更多相关文章

  1. .netcore 3.1高性能微服务架构:封装调用外部服务的接口方法--HttpClient客户端思路分析

    众所周知,微服务架构是由一众微服务组成,项目中调用其他微服务接口更是常见的操作.为了便于调用外部接口,我们的常用思路一般都是封装一个外部接口的客户端,使用时候直接调用相应的方法.webservice或 ...

  2. .netcore 3.1高性能微服务架构:webapi规范

    1.1 定义 1.基础接口:单一职责原则,每个接口只负责各自的业务,下接db,通用性强. 2.聚合接口:根据调用方需求聚合基础接口数据,业务性强. 1.2 协议 1. 客户端在通过 API 与后端服务 ...

  3. SpringCloud SpringBoot 前后端分离企业级微服务架构源码赠送

    基于SpringBoot2.x.SpringCloud和SpringCloudAlibaba并采用前后端分离的企业级微服务敏捷开发系统架构.并引入组件化的思想实现高内聚低耦合,项目代码简洁注释丰富上手 ...

  4. swagger2 接口文档,整个微服务接口文档

    1,因为整个微服务会有好多服务,比如会员服务,支付服务,订单服务,每个服务都集成了swagger 我们在访问的时候,不可能每个服务输入一个url 去访问,看起来很麻烦,所以我们需要在一个页面上集成整个 ...

  5. (1)学习笔记 ) ASP.NET CORE微服务 Micro-Service ---- 什么是微服务架构,.netCore微服务选型

    开发工具:VS2017 .Net Core 2.1 什么是微服务?单体结构: 缺点: 1)只能采用同一种技术,很难用不同的语言或者语言不同版本开发不同模块: 2)系统耦合性强,一旦其中一个模块有问题, ...

  6. (1).NET CORE微服务 Micro-Service ---- 什么是微服务架构,.netCore微服务选型

    开发工具:VS2017 .Net Core 2.1 什么是微服务?单体结构: 缺点:1)只能采用同一种技术,很难用不同的语言或者语言不同版本开发不同模块:2)系统耦合性强,一旦其中一个模块有问题,整个 ...

  7. 什么是微服务架构,.netCore微服务选型

    什么是微服务架构,.netCore微服务选型 https://www.cnblogs.com/uglyman/p/9182485.html 开发工具:VS2017 .Net Core 2.1 什么是微 ...

  8. 腾讯开源微服务架构 Tars,高性能 RPC 开发框架

    腾讯微服务架构 Tars 于今日正式开源. Tars 取名于电影“星际穿越”中的机器人,是支持多语言的高性能 RPC 开发框架和配套一体化的服务治理平台,可以帮助企业或者用户以微服务的方式快速构建稳定 ...

  9. 庐山真面目之八微服务架构 NetCore 基于 Dockerfile 文件部署

    庐山真面目之八微服务架构 NetCore 基于 Dockerfile 文件部署 一.简介      从今天开始,不出意外的话,以后所写的文章中所介绍项目的部署环境都应该会迁移到Linux环境上,而且是 ...

随机推荐

  1. TampeMonkey 关于 youtube的两个插件

    一个是 Video Speed Buttons 负责调速 一个是 YouTube Links  负责下载不同分辨率的视频

  2. 【01】HTML_day01_01-前言&WEB标准

    typora-copy-images-to: media 第01阶段.前端基础.认识WEB 基础班学习目标 目标: 能根据psd文件,用HTML+CSS 布局出符合W3C规范的网页. 网站首页 列表页 ...

  3. 查看mysql是否锁表了

    1.查看表是否被锁: (1)直接在mysql命令行执行:show engine innodb status\G. (2)查看造成死锁的sql语句,分析索引情况,然后优化sql. (3)然后show p ...

  4. jQuery XSS漏洞

    漏洞成因: jQuery中过滤用户输入数据所使用的正则表达式存在缺陷,可能导致location.hash跨站脚本攻击. 演示程序: <!DOCTYPE html> <html lan ...

  5. 【daily】Java枚举 - fastjson对enum的处理

    目的 1.枚举值转换成完全的json: 2.对象中的枚举成员完全转换成json: 3.枚举类的全部值转换成json: 枚举定义 public enum SongsEnum { SAFE_AND_SOU ...

  6. 剑指offer-面试题53_2-0~n-1中缺失的数字-二分查找

    /* 题目: 寻找递增数组0~n-1中缺失的数字. */ /* 思路: 变形二分法. */ #include<iostream> #include<cstring> #incl ...

  7. python 访问sql server数据库

    访问数据库 cnxn = pyodbc.connect("Driver={SQL Server};Server=localhost;Database=用户名;uid=sa;pwd=密码&qu ...

  8. 【剑指Offer】05、用两个栈实现队列

    题目描述 用两个栈来实现一个队列,完成队列的Push和Pop操作. 队列中的元素为int类型. 题解一: //stack2有元素就pop,没有元素就将stack1中所有元素倒进来再pop public ...

  9. Uva12716 素数筛思想的应用

    Uva12716 题意: 输入整数n,1<= n <=3e7,问有多少个整数对(a,b)满足:1 <= b <= a <= n,且gcd(a,b)== a XOR b 解 ...

  10. TCP 协议快被淘汰了,UDP 协议才是新世代的未来?

    TCP 协议可以说是今天互联网的基石,作为可靠的传输协议,在今天几乎所有的数据都会通过 TCP 协议传输,然而 TCP 在设计之初没有考虑到现今复杂的网络环境,当你在地铁上或者火车上被断断续续的网络折 ...