最近做的项目使用mvc+webapi，采取前后端分离的方式，后台提供API接口给前端开发人员。这个过程中遇到一个问题后台开发人员怎么提供接口说明文档给前端开发人员,最初打算使用word文档方式进行交流，实际操作中却很少动手去写。为了解决这个问题，特意在博客园中搜索了一下api接口文档生成的文章，引起我注意的有两种方案。1.微软自带的Microsoft.AspNet.WebApi.HelpPage 2.swagger（我比较喜欢戏称为“丝袜哥”）
最先尝试的是微软自带的方案，由于项目对webapi了一定改造导致使用该方案时一直报错，于是转向了第二种方案,经过大半天大捣鼓，最终效果如下
1.列出所有API控制器和控制器描述
2.列出action和描述
3.直观的接口测试
达到这几点目标，已经满足项目使用。
阅读目录
使用swagger1.创建webapi项目解决方案
2.引用swagger nuget包
Swashbuckle和Swagger.Net.UI两个包
3.卸载重复包Swagger.Net
引用Swagger.Net.UI时会引用Swagger.Net这个包，但是Swagger.Net的功能和Swashbuckle重复了。所以我采取了卸载Swagger.Net
删除多余的SwaggerUI文件夹
删除多余的配置类SwaggerNet
4.添加接口注释
完成上面三部运行项目，可以看到接口描述已经生成，浏览地址。但是没有接口的注释，下面添加接口注释
项目属性->勾选生成xml文档文件
修改SwaggerConfig文件
//c.IncludeXmlComments(GetXmlCommentsPath()); //设置接口描述xml路径地址 c.IncludeXmlComments(, System.AppDomain.CurrentDomain.BaseDirectory));
给接口添加注释，即可看到参数及方法描述了
汉化及问题解决经过上面的操作，已经完成了所需功能。但是还有几点问题需要完善
1.界面的说明都是英文的需要进行汉化
2.控制器没有描述
3.接口过多每次生成速度比较慢
1.汉化步骤
在SwaggerConfig配置文件中有这么一段代码
.EnableSwaggerUi(c =>{
//c.InjectJavaScript(thisAssembly, "Swashbuckle.Dummy.SwaggerExtensions.testScript1.js")
});
这段代码的作用是向页面输出引用Swashbuckle.Dummy.SwaggerExtensions.testScript1.js文件，或许会疑问js文件路径为什么这么奇怪。那是因为Swagger将资源文件都嵌入到dll中了，我们常用的资源文件都是以内容的方式放在项目中的，我们也可以以嵌入的资源方式引入到项目中
这也是上面我将SwaggerUI文件夹删除,页面也能正常出来的原因。资源文件都被打包到dll中了，为了验证这个说法，使用反编译工具reflector。来反编译一下Swashbuckle.Core.dll
弄清楚了实现原理，现在来实现汉化。添加自己的中文语言包，和转换js，实现逻辑参考swagger源码。
//c.InjectJavaScript(thisAssembly, "Swashbuckle.Dummy.SwaggerExtensions.testScript1.js"); //路径规则，项目命名空间.文件夹名称.js文件名称 c.InjectJavaScript(thisAssembly, );
/// <summary> /// 中文转换 /// </summary> var SwaggerTranslator = (function () { iexcute = 0, //中文语言包 _words = { "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": "应用", "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": "从路径", "Click to set as parameter value": "点击设置参数", "server returned": "服务器返回" }, //定时执行转换 _translator2Cn = function () { if ($("#resources_container .resource").length > 0) { _tryTranslate(); } if ($("#explore").text() == "Explore" && iexcute < 500) { iexcute++; setTimeout(_translator2Cn, 50); } }, //设置控制器注释 _setControllerSummary = function () { $.ajax({ type: "get", async: true, url: $("#input_baseUrl").val(), dataType: "json", success: function (data) { var summaryDict = data.ControllerDesc; var id, controllerName, strSummary; $("#resources_container .resource").each(function (i, item) { id = $(item).attr("id"); if (id) { controllerName = id.substring(9); strSummary = summaryDict[controllerName]; if (strSummary) { $(item).children(".heading").children(".options").prepend('<li title="' + strSummary + '">' + strSummary + '</li>'); } } }); } }); }, //尝试将英文转换成中文 _tryTranslate = function () { $('[data-sw-translate]').each(function () { $(this).html(_getLangDesc($(this).html())); $(this).val(_getLangDesc($(this).val())); $(this).attr('title', _getLangDesc($(this).attr('title'))); }); }, _getLangDesc = function (word) { return _words[$.trim(word)] !== undefined ? _words[$.trim(word)] : word; }; return { Translator: function () { document.title = "API描述文档"; $('body').append('<style type="text/css">.controller-summary{color:#10a54a !important;word-break:keep-all;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;max-width:250px;text-align:right;cursor:default;} </style>'); $("#logo").html("接口描述").attr("href", "/Home/Index"); //设置控制器描述 _setControllerSummary(); _translator2Cn(); } } })(); //执行转换 SwaggerTranslator.Translator();
2.控制器描述和接口文档缓存
相关文章
精彩导读
热门资讯
关注我们
