.NetCore使用Swagger+API多版本控制的流程分析

本文实例环境及版本.netcore3.1、swagger6.1

现在的开发大部分都是前后端分离的模式了，后端提供接口，前端调用接口。后端提供了接口，需要对接口进行测试，之前都是使用浏览器开发者工具，或者写单元测试，再或者直接使用postman，但是现在这些都已经out了。后端提供了接口，如何跟前端配合说明接口的性质，参数等这也是一个问题。有没有一种工具可以根据后端的接口自动生成接口文档，说明接口的性质，参数等信息，又能提供接口调用等相关功能呢？答案是有的。swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 restful 风格的 web 服务。而作为.net core开发，swashbuckle是swagger应用的首选！

总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码，允许 api 来始终保持同步。swagger 让部署管理和使用功能强大的 api 从未如此简单。

swashbuckle.aspnetcore源码地址：https://github.com/domaindrivendev/swashbuckle.aspnetcore

整个swagger页面访问流程如下：

　　1、浏览器输入swaggerui页面地址，比如：http://localhost:5000/swagger/index.html，这个地址是可配置的

　　2、请求被swaggerui中间件拦截，然后返回页面，这个页面是嵌入的资源文件，也可以设置成外部自己的页面文件（使用外部静态文件拦截）

　　3、页面接收到swagger的index页面后，会根据swaggerui中间件中使用swaggerendpoint方法设置的文档列表，加载第一个文档，也就是获取文档架构信息swagger.json

　　4、浏览器请求的swagger.json被swagger中间件拦截，然后解析属于请求文档的所有接口，并最终返回一串json格式的数据

　　5、浏览器根据接收到的swagger,json数据呈现ui界面

一、swagger基本使用

1、新建netcore项目，添加相关controller并添加引用swashbuckle.aspnetcore.swagger

2、在startup中添加配置

在configurervices中注入swashbuckle服务

rvices.addswaggergen(c =>{     c.swaggerdoc("v1", new openapiinfo     {           //版本            version = "v1",           //标题           title = $"接口文档-netcore3.1",           //描述           description = $"netcore http api v1",           //联系方式           contact = new openapicontact { name = "测试", email = "", url = new uri("https://www.cnblogs.com/mzflog/") },           licen = new openapilicen { name = "测试2", url = new uri("https://www.cnblogs.com/mzflog/") }      });      // 加载xml注释      c.includexmlcomments(xmlcommentsfilepath); });

新增xmlcommentsfilepath 属性，此时需要引用microsoft.extensions.platformabstractions

/// <summary> /// 获取当前项目名的xml文件 /// </summary> static string xmlcommentsfilepath {     get     {         var bapath = platformrvices.default.application.applicationbapath;         var filename = typeof(startup).gettypeinfo().asmbly.getname().name + ".xml";         return path.combine(bapath, filename);     }  }

光良约定歌词在configure中添加swagger中间件uswagger，uswaggerui

uswagger：添加swagger中间件，主要用于拦截swagger.json请求，从而可以获取返回所需的接口架构信息

uswaggerui：添加swaggerui中间件，主要用于拦截swagger/index.html页面请求，返回页面给前端

app.uswagger(); app.uswaggerui(c => {     c.swaggerendpoint($"/swagger/v1/swagger.json", $"netcore v1");     //c.routeprefix = string.empty;     //如果是为空 访问路径就为 根域名/index.html,注意localhost:8001/swagger是访问不到的     //路径配置，设置为空，表示直接在根域名（localhost:8001）访问该文件     c.routeprefix = "swagger"; // 如果你想换一个路径，直接写名字即可，比如直接写c.routeprefix = "swagger"; 则访问路径为 根域名/swagger/index.html });

右键项目属性在生成中添加xml

此时通过http://localhost:端口号/swagger即可访问

二、swagger结合版本控制

版本控制的好处：

　　1、有助于及时推出功能, 而不会破坏现有系统。

2、它还可以帮助为选定的客户提供额外的功能。

1、添加对microsoft.aspnetcore.mvc.versioning和microsoft.aspnetcore.mvc.versioning.apiexplorer的引用，本文使用版本4.1.0

2、在configurervices中

rvices.addapiversioning(option =>{      // 可选，为true时api返回支持的版本信息      option.reportapiversions = true;      // 请求中未指定版本时默认为1.0      option.defaultapiversion = new apiversion(1, 0);      //版本号以什么形式，什么字段传递      option.apiversionreader = apiversionreader.combine(new headerapiversionreader("api-version"));      // 在不提供版本号时，默认为1.0  如果不添加此配置，不提供版本号时会报错"message": "an api version is required, but was not specified."      //option.assumedefaultversionwhenunspecified = true;      //默认以当前最高版本进行访问      //option.apiversionlector = new currentimplementationapiversionlector(option); }).addversionedapiexplorer(opt => {      //以通知swagger替换控制器路由中的版本并配置api版本      opt.substituteapiversioninurl = true;      // 版本名的格式：v+版本号      opt.groupnameformat = "'v'vvv";      //是否提供api版本服务      opt.assumedefaultversionwhenunspecified = true; });

//方式一 （不建议使用）   此种方式报警告：asp0000 从应用程序代码调用“buildrviceprovider”会导致创建单例服务的附加副本。考虑替代方案，例如将依赖注入服务作为“配置”的参数 rvices.addswaggergen(options => {       // 解析iapiversiondescriptionprovider服务       var provider = rvices.buildrviceprovider().getrequiredrvice<iapiversiondescriptionprovider>();       //为每个发现的api版本添加一个swagger文档 可跳过不需要记录的       foreach (var description in provider.apiversiondescriptions)       {            options.swaggerdoc(description.groupname, createinfoforapiversion(description));       }　　　　 //加载xml注释  并启用控制器的注释信息默认为fal不启用       options.includexmlcomments(xmlc青春期的症状ommentsfilepath,true);  });//方式二 （建议使用）rvices.addswaggergen();//解决上面报asp0000警告的方案rvices.addoptions<swaggergenoptions>()        .configure<i嘎羧apiversiondescriptionprovider>((options, rvice) =>        {             options.resolveconflictingactions(apidescriptions => apidescriptions.first());             // 添加文档信息             foreach (var item in rvice.apiversiondescriptions)             {                 options.swaggerdoc(item.groupname, createinfoforapiversion(item));             }             //给swagger添加过滤器             //options.operationfilter<swaggerparameterfilter>();             // 加载xml注释             options.includexmlcomments(xmlcommentsfilepath, true);        });

添加createinfoforapiversion方法

static openapiinfo createinfoforapiversion(apiversiondescription description) {       var info = new openapiinfo()       {             //标题             title = $".net core api for 测试项目 {description.apiversion}",             //当前版本             version = description.apiversion.tostring(),             //文档说明             description = "api项目 当前环境-" + environmentname,             //联系方式             contact = new openapicontact() { name = "标题", email = "", url = null },             termsofrvice = new uri(""),             //许可证             licen = new openapilicen() { name = "文档", url = new uri("") }         };　　　　　 //当有弃用标记时的提示信息         if (description.isdeprecated)         {             info.description += " - 此版本已放弃兼容";         }         return info;   }

3、在configure中添加

iapiversiondescriptionprovider：用于枚举定义的api版本的api版本描述符提供程序

public void configure(iapplicationbuil美丽的图画电影der app, iwebhostenvironment env, iapiversiondescriptionprovider provider)

//添加swagger中间件，主要用于拦截swagger.json请求，从而可以获取返回所需的接口架构信息app.uswagger(opt =>{      //路由模板，默认值是/swagger/{documentname}/swagger.json，这个属性很重要！而且这个属性中必须包含{documentname}参数。      //opt.routetemplate= "/swagger/{documentname}/swagger.json";      // 表示按swagger2.0格式序列化生成swagger.json，这个不推荐使用，尽可能的使用新版本的就可以了      //opt.rializeasv2 }); //添加swaggerui中间件，主要用于拦截swagger / index.html页面请求，返回页面给前端 app.uswaggerui(options => {       // 为每个版本创建一个json       foreach (var description in provider.apiversiondescriptions)       {             //这个属性是往swaggerui页面head标签中添加我们自己的代码，比如引入一些样式文件，或者执行自己的一些脚本代码             //options.headcontent += $"<script type='text/javascript'>alert('欢迎来到swaggerui页面')</script>";             //展示默认头部显示的下拉版本信息             //options.swaggerendpoint($"/swagger/{descri情乱夜中环ption.groupname}/swagger.json", description.groupname.toupperinvariant());             //自由指定头部显示的下拉版本内容             options.swaggerendpoint($"/swagger/{description.groupname}/swagger.json", "coreapi" + description.apiversion);              //如果是为空 访问路径就为 根域名/index.html,注意localhost:8001/swagger是访问不到的              //options.routeprefix = string.empty;              // 如果你想换一个路径，直接写名字即可，比如直接写c.routeprefix = "swagger"; 则访问路径为 根域名/swagger/index.html              options.routeprefix = "swagger";        }  });

4、在api的controller中添加版本

[apiversion("1.0", deprecated = fal)] //deprecated是否弃用该版本 默认为fal不弃用。即使标记了弃用此接口还是会显示，只是做个提示此版本将会被弃用了。 [route("api/[controller]")] [apicontroller] //[apiexplorerttings(ignoreapi = true)] 隐藏该接口controller public class valuescontroller : controller [obsolete] //弃用该action方法 [apiexplorerttings(ignoreapi = true)] //隐藏该action方法 public ienumerable<string> get()

为体验版本控制在新建一个控制器并添加 [apiversion(“2.0”)]

此时访问页面，在右侧的下拉框中可选择不同的版本，会展示不同版本下的控制器。

才疏学浅，相关文档等仅供自我总结，如有相关问题可留言交流谢谢。

原文地址：/d/file/titlepic/14969620.html