在ABP模板项目中，通过SwaggerUI可以为我们的WebApi生成动态的可交互接口文档页面，从而可以很方便的测试调用我们的WebApi接口。

一、集成Swagger

右键项目YoYo.Web，打开NuGet程序包管理器，添加Swashbuckle。

其中包含了程序和UI，安装后在App_Start文件夹下生成SwaggerConfig.cs。



完成这一步，Swagger已经集成完毕。

可以访问http://localhost:XXXX/swagger/ui/index。



如果出现异常，可以先尝试取消注释SwaggerConfig.cs中的此行代码

  1. c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());

二、增强配置

包括从XML接口文档读取，修改规则，汉化

swaggerconfig.cs修改如下：

  1. using System.Web.Http;
  2. using WebActivatorEx;
  3. using YoYo.Web;
  4. using Swashbuckle.Application;
  5. using System.Linq;
  6. using System.IO;
  8. [assembly: PreApplicationStartMethod(typeof(SwaggerConfig), "Register")]
  10. namespace YoYo.Web
  11. {
  12.     public class SwaggerConfig
  13.     {
  14.         public static void Register()
  15.         {
  16.             var thisAssembly = typeof(SwaggerConfig).Assembly;
  18.             GlobalConfiguration.Configuration
  19.                 .EnableSwagger(c =>
  20.                     {
  21.                         c.SingleApiVersion("v1", "YoYo");
  22.                         c.IncludeXmlComments(GetXmlCommentsPath("WebApi"));
  23.                         c.IncludeXmlComments(GetXmlCommentsPath("Application"));
  24.                         c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());
  25.                         c.CustomProvider((defaultProvider) => new CachingSwaggerProvider(defaultProvider));
  26.                     })
  27.                 .EnableSwaggerUi(c =>
  28.                     {
  29.                         string resourceName = thisAssembly.FullName.Substring(0, thisAssembly.FullName.IndexOf(",")) + ".Scripts.swaggerui.swagger_lang.js";
  30.                         c.InjectJavaScript(thisAssembly, resourceName);
  31.                     });
  32.         }
  33.         private static string GetXmlCommentsPath(string subName)
  34.         {
  35.             return Directory.GetFiles(System.AppDomain.CurrentDomain.BaseDirectory + "bin\\").FirstOrDefault(n => n.ToLower().EndsWith(subName.ToLower() + ".xml"));
  36.         }
  37.     }
  38. }

在App_Start下新增文件CachingSwaggerProvider.cs

  1. using Microsoft.Ajax.Utilities;
  2. using Swashbuckle.Swagger;
  3. using System;
  4. using System.Collections.Concurrent;
  5. using System.Collections.Generic;
  6. using System.IO;
  7. using System.Linq;
  8. using System.Web;
  9. using System.Xml;
  11. namespace YoYo.Web
  12. {
  13.     public class CachingSwaggerProvider : ISwaggerProvider
  14.     {
  15.         private static ConcurrentDictionary<string, SwaggerDocument> _cache =
  16.             new ConcurrentDictionary<string, SwaggerDocument>();
  18.         private readonly ISwaggerProvider _swaggerProvider;
  20.         public CachingSwaggerProvider(ISwaggerProvider swaggerProvider)
  21.         {
  22.             _swaggerProvider = swaggerProvider;
  23.         }
  25.         public SwaggerDocument GetSwagger(string rootUrl, string apiVersion)
  26.         {
  27.             var cacheKey = string.Format("{0}_{1}", rootUrl, apiVersion);
  28.             SwaggerDocument srcDoc = null;
  29.             //只读取一次
  30.             if (!_cache.TryGetValue(cacheKey, out srcDoc))
  31.             {
  32.                 srcDoc = _swaggerProvider.GetSwagger(rootUrl, apiVersion);
  34.                 srcDoc.paths.ForEach(n =>
  35.                 {
  36.                     SetOperation(n.Value.delete);
  37.                     SetOperation(n.Value.get);
  38.                     SetOperation(n.Value.head);
  39.                     SetOperation(n.Value.options);
  40.                     SetOperation(n.Value.patch);
  41.                     SetOperation(n.Value.post);
  42.                     SetOperation(n.Value.put);
  43.                 });
  45.                 srcDoc.vendorExtensions = new Dictionary<string, object> { { "ControllerDesc", GetControllerDesc() } };
  46.                 _cache.TryAdd(cacheKey, srcDoc);
  47.             }
  48.             return srcDoc;
  49.         }
  51.         private void SetOperation(Operation operation)
  52.         {
  53.             if (operation != null)
  54.             {
  55.                 operation.tags[0] = operation.tags[0].Split('_').Last();
  57.                 if (operation.parameters == null)
  58.                 {
  59.                     operation.parameters = new List<Parameter>();
  60.                 }
  61.                 operation.parameters.Insert(0, new Parameter()
  62.                 {
  63.                     @in = "header",
  64.                     name = "authorization",
  65.                     description = "token",
  66.                     type = "string"
  67.                 });
  68.                 operation.parameters.Insert(0, new Parameter()
  69.                 {
  70.                     @in = "header",
  71.                     name = "X-XSRF-TOKEN",
  72.                     description = "XSRF-TOKEN",
  73.                     type = "string"
  74.                 });
  76.                 if (operation.operationId.StartsWith("Import"))
  77.                 {
  78.                     operation.parameters.Add(new Parameter()
  79.                     {
  80.                         @in = "formData",
  81.                         name = "",
  82.                         type = "file"
  83.                     });
  84.                     if (operation.consumes == null)
  85.                     {
  86.                         operation.consumes = new List<string>();
  87.                     }
  88.                     operation.consumes.Add("multipart/form-data");
  89.                 }
  90.             }
  91.         }
  93.         /// <summary>
  94.         /// 从API文档中读取控制器描述
  95.         /// </summary>
  96.         /// <returns>所有控制器描述</returns>
  97.         public static ConcurrentDictionary<string, string> GetControllerDesc()
  98.         {
  99.             ConcurrentDictionary<string, string> controllerDescDict = new ConcurrentDictionary<string, string>();
  101.             GetControllerDescByProject("WebApi", "Controller", controllerDescDict);
  102.             GetControllerDescByProject("Application", "AppService", controllerDescDict);
  104.             return controllerDescDict;
  105.         }
  107.         private static void GetControllerDescByProject(string subName, string endsWith, ConcurrentDictionary<string, string> controllerDescDict)
  108.         {
  109.             string xmlpath = Directory.GetFiles(System.AppDomain.CurrentDomain.BaseDirectory + "bin\\").FirstOrDefault(n => n.ToLower().EndsWith(subName.ToLower() + ".xml"));
  110.             if (File.Exists(xmlpath))
  111.             {
  112.                 XmlDocument xmldoc = new XmlDocument();
  113.                 xmldoc.Load(xmlpath);
  114.                 string type = string.Empty, path = string.Empty, controllerName = string.Empty;
  116.                 string[] arrPath;
  117.                 int length = -1, cCount = endsWith.Length;
  118.                 XmlNode summaryNode = null;
  119.                 foreach (XmlNode node in xmldoc.SelectNodes("//member"))
  120.                 {
  121.                     type = node.Attributes["name"].Value;
  122.                     if (type.StartsWith("T:"))
  123.                     {
  124.                         //控制器
  125.                         arrPath = type.Split('.');
  126.                         length = arrPath.Length;
  127.                         controllerName = arrPath[length - 1];
  128.                         if (controllerName.EndsWith(endsWith))
  129.                         {
  130.                             //获取控制器注释
  131.                             summaryNode = node.SelectSingleNode("summary");
  132.                             string key = controllerName.StartsWith("I") ?
  133.                                 controllerName.Substring(1, 1).ToLower() + controllerName.Substring(2, controllerName.Length - 2 - cCount) :
  134.                                 controllerName.Remove(controllerName.Length - cCount, cCount);
  135.                             if (summaryNode != null && !string.IsNullOrEmpty(summaryNode.InnerText) && !controllerDescDict.ContainsKey(key))
  136.                             {
  137.                                 controllerDescDict.TryAdd(key, summaryNode.InnerText.Trim());
  138.                             }
  139.                         }
  140.                     }
  141.                 }
  142.             }
  143.         }
  144.     }
  145. }

swagger_lang.js，需要将文件属性的“生成操作”设置为“嵌入的资源”，代码如下

  1. ///    <summary>
  2. /// 中文转换
  3. ///    </summary>
  4. var SwaggerTranslator = (function () {
  5.     //定时执行检测是否转换成中文,最多执行500次  即500*50/1000=25s
  6.     var iexcute = 0,
  7.         //中文语言包
  8.         _words = {
  9.             "Warning: Deprecated": "警告：已过时",
  10.             "Implementation Notes": "实现备注",
  11.             "Response Class": "响应类",
  12.             "Status": "状态",
  13.             "Parameters": "参数",
  14.             "Parameter": "参数",
  15.             "Value": "值",
  16.             "Description": "描述",
  17.             "Parameter Type": "参数类型",
  18.             "Data Type": "数据类型",
  19.             "Response Messages": "响应消息",
  20.             "HTTP Status Code": "HTTP状态码",
  21.             "Reason": "原因",
  22.             "Response Model": "响应模型",
  23.             "Request URL": "请求URL",
  24.             "Response Body": "响应体",
  25.             "Response Code": "响应码",
  26.             "Response Headers": "响应头",
  27.             "Hide Response": "隐藏响应",
  28.             "Headers": "头",
  29.             "Try it out!": "试一下！",
  30.             "Show/Hide": "显示/隐藏",
  31.             "List Operations": "显示操作",
  32.             "Expand Operations": "展开操作",
  33.             "Raw": "原始",
  34.             "can't parse JSON.  Raw result": "无法解析JSON. 原始结果",
  35.             "Model Schema": "模型架构",
  36.             "Model": "模型",
  37.             "apply": "应用",
  38.             "Username": "用户名",
  39.             "Password": "密码",
  40.             "Terms of service": "服务条款",
  41.             "Created by": "创建者",
  42.             "See more at": "查看更多：",
  43.             "Contact the developer": "联系开发者",
  44.             "api version": "api版本",
  45.             "Response Content Type": "响应Content Type",
  46.             "fetching resource": "正在获取资源",
  47.             "fetching resource list": "正在获取资源列表",
  48.             "Explore": "浏览",
  49.             "Show Swagger Petstore Example Apis": "显示 Swagger Petstore 示例 Apis",
  50.             "Can't read from server.  It may not have the appropriate access-control-origin settings.": "无法从服务器读取。可能没有正确设置access-control-origin。",
  51.             "Please specify the protocol for": "请指定协议：",
  52.             "Can't read swagger JSON from": "无法读取swagger JSON于",
  53.             "Finished Loading Resource Information. Rendering Swagger UI": "已加载资源信息。正在渲染Swagger UI",
  54.             "Unable to read api": "无法读取api",
  55.             "from path": "从路径",
  56.             "Click to set as parameter value": "点击设置参数",
  57.             "server returned": "服务器返回"
  58.         },
  60.         //定时执行转换
  61.         _translator2Cn = function () {
  62.             if ($("#resources_container .resource").length > 0) {
  63.                 _tryTranslate();
  64.             }
  66.             if ($("#explore").text() === "Explore" && iexcute < 500) {
  67.                 iexcute++;
  68.                 setTimeout(_translator2Cn, 50);
  69.             }
  70.         },
  72.         //设置控制器注释
  73.         _setControllerSummary = function () {
  74.             $.ajax({
  75.                 type: "get",
  76.                 async: true,
  77.                 url: $("#input_baseUrl").val(),
  78.                 dataType: "json",
  79.                 success: function (data) {
  80.                     var summaryDict = data.ControllerDesc;
  81.                     var id, controllerName, strSummary;
  82.                     $("#resources_container .resource").each(function (i, item) {
  83.                         id = $(item).attr("id");
  84.                         if (id) {
  85.                             controllerName = id.substring(9);
  86.                             strSummary = summaryDict[controllerName];
  87.                             if (strSummary) {
  88.                                 $(item).children(".heading").children(".options").prepend('<li class="controller-summary" title="' + strSummary + '">' + strSummary + '</li>');
  89.                             }
  90.                         }
  91.                     });
  92.                 }
  93.             });
  94.         },
  96.         //尝试将英文转换成中文
  97.         _tryTranslate = function () {
  98.             $('[data-sw-translate]').each(function () {
  99.                 $(this).html(_getLangDesc($(this).html()));
  100.                 $(this).val(_getLangDesc($(this).val()));
  101.                 $(this).attr('title', _getLangDesc($(this).attr('title')));
  102.             });
  103.         },
  104.         _getLangDesc = function (word) {
  105.             return _words[$.trim(word)] !== undefined ? _words[$.trim(word)] : word;
  106.         };
  108.     return {
  109.         Translator: function () {
  110.             document.title = "API描述文档";
  111.             $('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>');
  112.             $("#logo").html("接口描述").attr("href", "/Home/Index");
  113.             //设置控制器描述
  114.             _setControllerSummary();
  115.             _translator2Cn();
  116.         }
  117.     }
  118. })();
  119. //执行转换
  120. SwaggerTranslator.Translator();
  122. function setCookie(c_name, value, expiredays) {
  123.     var exdate = new Date()
  124.     exdate.setDate(exdate.getDate() + expiredays)
  125.     document.cookie = c_name + "=" + escape(value) +
  126.         ((expiredays == null) ? "" : ";expires=" + exdate.toGMTString())
  127. }
  129. function getCookie(c_name) {
  130.     if (document.cookie.length > 0) {
  131.         c_start = document.cookie.indexOf(c_name + "=")
  132.         if (c_start != -1) {
  133.             c_start = c_start + c_name.length + 1
  134.             c_end = document.cookie.indexOf(";", c_start)
  135.             if (c_end == -1) c_end = document.cookie.length
  136.             return unescape(document.cookie.substring(c_start, c_end))
  137.         }
  138.     }
  139.     return ""
  140. }
  142. var token = getCookie("xToken");
  143. if (token) {
  144.     $('[name="authorization"]').val(token);
  145. }
  147. var XSRFToken = getCookie("XSRF-TOKEN");
  148. if (XSRFToken) {
  149.     $('[name="X-XSRF-TOKEN"]').val(XSRFToken);
  150. }
  152. var setToken = function () {
  153.     var json = $("#resource_Account .response_body.json").text()
  154.     if (json) {
  155.         var obj = eval('(' + json + ')');
  156.         if (obj.result) {
  157.             $('[name="authorization"]').val("Bearer " + obj.result);
  158.             setCookie("xToken", "Bearer " + obj.result);
  159.         }
  160.     }
  161. }
  163. setInterval(setToken, 5000)

另外，在Application和WebApi的项目属性，生成输出中，勾选“XML文档文件”，如下图

三、最终效果

代码中还为接口自动添加了X-XSRF-TOKEN和authorization两个参数，可以让我们更方便的调用加了权限的接口。

ABP给WebApi添加SwaggerUI,生成可交互接口文档的更多相关文章

  1. Asp.Net Core2.0 WebAPI 使用Swagger生成漂亮的接口文档

    1.引用NuGet: Swashbuckle.AspNetCore.Swagger Swashbuckle.AspNetCore.SwaggerGen 或 <PackageReference I ...

  2. 整合swagger2生成Restful Api接口文档

    整合swagger2生成Restful Api接口文档 swagger Restful文档生成工具 2017-9-30 官方地址:https://swagger.io/docs/specificati ...

  3. Swagger 生成 PHP API 接口文档

    Swagger 生成 PHP API 接口文档 Lumen微服务生成Swagger文档 1.概况 有同学反馈写几十个接口文档需要两天的工作量, 随着多部门之间的协作越来越频繁, 维护成本越来越高, 文 ...

  4. 如何快速方便的生成好看的接口文档(apipost生成文档)

    一键生成文档 我们在"2分钟玩转APIPOST"一讲中,简单介绍了如何生成并分享接口文档: 点击分享文档 复制并打开文档地址就可以看到了完整的接口文档. 本节课主要是讲解一些需要注 ...

  5. 如何使用Swagger-UI在线生成漂亮的接口文档

    一.简单介绍 Swagger是一个实现了OpenAPI(OpenAPI Specification)规范的工具集.OpenAPI是Linux基金会的一个项目,试图通过定义一种用来描述API格式或API ...

  6. Abp中SwaggerUI的多个接口文档配置说明

    对外提供的接口在实际生成过程中,可能是需要一个接口版本的,比如说v1,manage.效果如下:     在swagger中怎么实现呢? 1. 添加SwaggerVersionHelper.cs pub ...

  7. SpringBoot结合swagger2快速生成简单的接口文档

    1. pom.xml中加入依赖 <dependency> <groupId>com.spring4all</groupId> <artifactId>s ...

  8. 自动生成web api接口文档

    然后打开web程序,访问ip:port/Help. 为什么可以直接输入Help就能访问呢,因为这个插件本身已经配置了路径,如下. public class HelpPageAreaRegistrati ...

  9. Java | Spring Boot Swagger2 集成REST ful API 生成接口文档

      Spring Boot Swagger2 集成REST ful API 生成接口文档 原文 简介 由于Spring Boot 的特性,用来开发 REST ful 变得非常容易,并且结合 Swagg ...

随机推荐

  1. 四、Java多人博客系统-2.0版本

    由于时间关系,多人博客系统这里穿插一个2.0版本. 2.0版本本来是打算用于建立个人网站,但是后来发现个人建站需要购买域名服务器,还需要备案,很繁琐.最终放弃.完成此版本,最终也只是作为技术演练.此版 ...

  2. apache beam ElasticSearchIO 遇到异常后job中断执行 自己定制beam IO

    可以将 ElasticSearchIO.java 源码拷贝至自己的项目.改名为MyElasticSearchIO.java.自己定制实现.这时编译会遇到auto.value失败.在pom.xml中加入 ...

  3. FreeNAS：创建 CIFS 匿名共享

    第一部分:数据集权限设定 浏览器访问 FreeNAS 系统的 WebGUI 管理界面,点选 “Storage” 存储图标打开存储选项卡,在卷列表中点选用于匿名共享的数据集,如有需要,也可以自行创建新的 ...

  4. (二叉树 递归) leetcode 106. Construct Binary Tree from Inorder and Postorder Traversal

    Given inorder and postorder traversal of a tree, construct the binary tree. Note:You may assume that ...

  5. 【强大精美的PS特效滤镜合集】Alien Skin Eye Candy for Mac 7.2.2.20

    [简介] Alien Skin Eye Candy for Mac 7.2.2 版本,支持最新的PhotoShop CC 2019.2018等版本,这是一款强大酷炫的PS特效滤镜合集,具有32种滤镜和 ...

  6. Python动态语言的特性

    一.动态语言相关概念 1.1 动态语言 在运行时代码可以根据某些条件改变自身结构 可以在运行时引进新的函数.对象.甚至代码,可以删除已有的函数等其他结构上的变化 常见的动态语言:Object-C.C# ...

  7. Web请求相关

    HTTP简介 HTTP协议是Hyper Text Transfer Protocol(超文本传输协议)的缩写,是用于从万维网(WWW:World Wide Web )服务器传输超文本到本地浏览器的传送 ...

  8. 1.5分布式通讯框架-RMI

    分布式通信框架-RMI讲解 什么是RPC Remote procedure call protocal RPC协议其实是一个规范.常用PRC框架:Dubbo.Thrif.RMI.Webservice. ...

  9. Hadoop记录- Yarn scheduler队列采集

    #!/bin/sh ip=10.116.100.11 port=8088 export HADOOP_HOME=/app/hadoop/bin rmstate1=$($HADOOP_HOME/yarn ...

  10. Contest2158 - 2019-3-14 高一noip基础知识点 测试3 题解版

    传送门 预计得分:0 实际得分:90 还行 T1 数学卡精 二分double卡精 反正就是卡精 怎么办?卡回去!! 将double*=1e4,变成一个long long 注意四舍五入的奇技淫巧 代码 ...