.Net WebApi接口Swagger集成简单使用
swagger介绍
swagger 是一款restful接口的、基于yaml、json语言的文档在线自动生成、代码自动生成的工具。而我最近做的项目用的是webapi,前后端完全分离,这时后端使用swagger就能够很方便简洁的把所写的接口以及相关注释展示给前端人员,
从而方便双方的沟通,提高工作效率。
官网地址:
开始使用swagger
1.首先创建一个空的webapi项目
2.添加swagger nuget包 swashbuckle
安装完成后开始配置swagger
第一步:输出xml文档文件,右键点击webapi项目属性,找到生成一栏,并在 输出xml文档文件 选项中打钩。
第二步:swagger包安装完以后会自动在webapi项目的app_start文件夹下生成swaggerconfig配置类,程序初始化时会执行此配置类的代码。所以要在此配置你想要实现的功能。
初始内容如下图(博主把多余的注释代码都删掉了,并做了一点修改,所以看起来简洁一点)
在enableswagger 配置匿名方法中注册要读取的xml文件路径
上图中的getxmlcommentspath方法代码如下:
/// <summary> /// 获取xml路径 /// </summary> /// <returns></returns> protected static string getxmlcommentspath() { return system.string.format(@"{0}\bin\webapitest.xml",system.appdomain.currentdomain.basedirectory); }
注册完xml路径以后,就要开始写控制器描述和接口文档缓存的代码了
先在app_start文件夹中新建一个cachingswaggerprovider类,并实现iswaggerprovider接口
代码如下
/// <summary> /// 读取api接口注释实现类 /// </summary> public class cachingswaggerprovider : iswaggerprovider { private static concurrentdictionary<string,swaggerdocument> _cache = new concurrentdictionary<string,swaggerdocument>(); private readonly iswaggerprovider _swaggerprovider; /// <summary> /// 构造 /// </summary> /// <param name="swaggerprovider"></param> public cachingswaggerprovider(iswaggerprovider swaggerprovider) { _swaggerprovider = swaggerprovider; } /// <summary> /// 获取文档 /// </summary> /// <param name="rooturl"></param> /// <param name="apiversion"></param> /// <returns></returns> public swaggerdocument getswagger(string rooturl,string apiversion) { var cachekey = string.format("{0}_{1}",rooturl,apiversion); swaggerdocument srcdoc = null; //只读取一次 if (!_cache.trygetvalue(cachekey,out srcdoc)) { //appendmodeltocurrentxml(); srcdoc = _swaggerprovider.getswagger(rooturl,apiversion); srcdoc.vendorextensions = new dictionary<string,object> { { "controllerdesc",getcontrollerdesc() },{ "","" } }; _cache.tryadd(cachekey,srcdoc); } return srcdoc; } /// <summary> /// 从api文档中读取控制器描述 /// </summary> /// <returns>所有控制器描述</returns> public static concurrentdictionary<string,string> getcontrollerdesc() { string xmlpath = string.format(@"{0}\bin\webapitest.xml",appdomain.currentdomain.basedirectory); concurrentdictionary<string,string> controllerdescdict = new concurrentdictionary<string,string>(); if (file.exists(xmlpath)) { xmldocument xmldoc = new xmldocument(); xmldoc.load(xmlpath); string type = string.empty, path = string.empty, controllername = string.empty; string[] arrpath; int length = -1, ccount = "controller".length; xmlnode summarynode = null; foreach (xmlnode node in xmldoc.selectnodes("//member")) { type = node.attributes["name"].value; if (type.startswith("t:")) { //控制器 arrpath = type.split('.'); length = arrpath.length; controllername = arrpath[length - 1]; if (controllername.endswith("controller")) { //获取控制器注释 summarynode = node.selectsinglenode("summary"); string key = controllername.remove(controllername.length - ccount,ccount); if (summarynode != null && !string.isnullorempty(summarynode.innertext) && !controllerdescdict.containskey(key)) { controllerdescdict.tryadd(key,summarynode.innertext.trim()); } } } } } return controllerdescdict; } }
下一步在enableswagger 配置匿名方法中注册cachingswaggerprovider
全部都配置好后我们来看下效果,运行项目,并打开文档地址://swagger/ui/index
此时我们发现文档内容虽然出来了,但控制器的描述并没有显示,而且文档内容很多都是英文注释,并不是很好理解,所以就要执行汉化操作了(注:由于控制器描述是由于通过js读取的,所以只有汉化后才是显示)。
汉化swagger文档内容
1.在当前webapi项目下新建名为swagger的js文件,并把下面的代码全部粘贴进去
'use strict'; window.swaggertranslator = { _words: [], translate: function () { var $this = this; $('[data-sw-translate]').each(function () { $(this).html($this._trytranslate($(this).html())); $(this).val($this._trytranslate($(this).val())); $(this).attr('title', $this._trytranslate($(this).attr('title'))); }); }, setcontrollersummary: function () { try { console.log($("#input_baseurl").val()); $.ajax({ type: "get", async: true, url: $("#input_baseurl").val(), datatype: "json", success: function (data) { var summarydict = data.controllerdesc; console.log(summarydict); var id, controllername, strsummary; $("#resources_container .resource").each(function (i, item) { id = $(item).attr("id"); if (id) { controllername = id.substring(9); try { strsummary = summarydict[controllername]; if (strsummary) { $(item).children(".heading").children(".options").first().prepend('<li class="controller-summary" style="color:green;" title="' + strsummary + '">' + strsummary + '</li>'); } } catch (e) { console.log(e); } } }); } }); } catch (e) { console.log(e); } }, _trytranslate: function (word) { return this._words[$.trim(word)] !== undefined ? this._words[$.trim(word)] : word; }, learn: function (wordsmap) { this._words = wordsmap; } }; /* jshint quotmark: double */ window.swaggertranslator.learn({ "warning: deprecated": "警告:已过时", "implementation notes": "实现备注", "response class": "响应类", "status": "状态", "parameters": "参数", "parameter": "参数", "value": "值", "description": "描述", "parameter type": "参数类型", "data type": "数据类型", "response messages": "响应消息", "http status code": "http状态码", "reason": "原因", "response model": "响应模型", "request url": "请求url", "response body": "响应体", "response code": "响应码", "response headers": "响应头", "hide response": "隐藏响应", "headers": "头", "try it out!": "试一下!", "show/hide": "显示/隐藏", "list operations": "显示操作", "expand operations": "展开操作", "raw": "原始", "can't parse json. raw result": "无法解析json. 原始结果", "model schema": "模型架构", "model": "模型", "apply": "应用", "example value": "实例值", "username": "用户名", "password": "密码", "terms of service": "服务条款", "created by": "创建者", "see more at": "查看更多:", "contact the developer": "联系开发者", "api version": "api版本", "response content type": "响应content type", "fetching resource": "正在获取资源", "fetching resource list": "正在获取资源列表", "explore": "浏览", "show swagger petstore example apis": "显示 swagger petstore 示例 apis", "can't read from server. it may not have the appropriate access-control-origin settings.": "无法从服务器读取。可能没有正确设置access-control-origin。", "please specify the protocol for": "请指定协议:", "can't read swagger json from": "无法读取swagger json于", "finished loading resource information. rendering swagger ui": "已加载资源信息。正在渲染swagger ui", "unable to read api": "无法读取api", "from path": "从路径", "server returned": "服务器返回" }); $(function () { window.swaggertranslator.translate(); window.swaggertranslator.setcontrollersummary(); });
2.右键swagger.js文件打开属性,把生成操作改为嵌入的资源,如下图:
3.在enableswaggerui配置匿名方法中注册js
我们再来看一下效果
我们可以看到控制器的描述已经可以看到,所以得英文注释也被汉化,文档也方便了很多了。
注:博主添加的webapi项目并没有引用外部项目,所以只需读取本项目内的xml文件,如果需要展示外部项目对象的注释,只需要在enableswagger 配置匿名方法中再注册一个要读取的外部xml文件路径即可。
其实上述控制器的描述文档我觉得并不够直观,所以我又自己给控制器做了分组,觉得这样更利于管理和维护。大家也可以根据自己的喜好做选择了。方法如下:
1.在app_start文件夹下新建controllergroupattribute特性类,并继承attribute,具体代码如下:
/// <summary> /// controller描述信息 /// </summary> [attributeusage(attributetargets.class,allowmultiple = false)] public class controllergroupattribute : attribute { /// <summary> /// 当前controller所属模块 请用中文 /// </summary> public string groupname { get; private set; } /// <summary> /// 当前controller用途 请用中文 /// </summary> public string useage { get; private set; } /// <summary> /// controller描述信息 构造 /// </summary> /// <param name="groupname">模块名称</param> /// <param name="useage">当前controller用途</param> public controllergroupattribute(string groupname,string useage) { if (string.isnullorempty(groupname) || string.isnullorempty(useage)) { throw new argumentnullexception("分组信息不能为空"); } groupname = groupname; useage = useage; } }
2.在enableswagger配置匿名方法中注册swagger分组
3.给控制器加controllergroup特性,并填写相关描述。
看下最终的效果图:
显示的还是比较直观的,哈哈!
另外有一点需要扩展的是,有时候可能某些接口并不想暴露出来,这也是可以实现的,方法如下:
1.在app_start文件夹中新建hiddenapifilter类,并继承idocumentfilter接口。然后新建个空的hiddenapi过滤器,并且此过滤器只可以用于方法和类,加上attributeusage特性即可。代码如下:
/// <summary> /// 隐藏指定api接口 /// </summary> [attributeusage(attributetargets.method | attributetargets.class)] public class hiddenapiattribute : attribute { } /// <summary> /// 接口过滤 /// </summary> public class hiddenapifilter: idocumentfilter { /// <summary> /// 获取指定显示接口 /// </summary> /// <param name="swaggerdoc"></param> /// <param name="schemaregistry"></param> /// <param name="apiexplorer"></param> public void apply(swaggerdocument swaggerdoc,schemaregistry schemaregistry,iapiexplorer apiexplorer) { foreach (apidescription apidescription in apiexplorer.apidescriptions) { if (enumerable.oftype<hiddenapiattribute>(apidescription.getcontrollerandactionattributes<hiddenapiattribute>()).any()) { string key = "/" + apidescription.relativepath; if (key.contains("?")) { int idx = key.indexof("?",stringcomparison.ordinal); key = key.substring(0,idx); } swaggerdoc.paths.remove(key); } } } }
2.在enableswagger配置匿名方法中注册
3.把此特性直接给指定的控制器或者接口方法用即可隐藏相关信息了!
总结
swagger方便简洁,能够很大的提高我们的工作效率,还是值得一用的。
上一篇: 关联本地Git仓库和Github仓库
下一篇: 钱算什么
推荐阅读
-
Asp.Net Core WebAPI使用Swagger时API隐藏和分组详解
-
Asp.net core WebApi 使用Swagger生成帮助页实例
-
Asp.Net Core WebAPI使用Swagger时API隐藏和分组详解
-
ASP.NET Core 3.0 WebApi中使用Swagger生成API文档简介
-
Asp.net core WebApi 使用Swagger生成帮助页实例
-
ASP.NET Core 2.2 WebApi 系列【四】集成Swagger
-
AspNetCore网关集成Swagger访问使用IdentityServer保护的webapi项目
-
记Asp.Net Core Swagger 使用 并带域接口处理
-
如何使用签名保证ASP.NET MVC OR WEBAPI的接口安全
-
asp.net core 系列之webapi集成Dapper的简单操作教程