zoukankan      html  css  js  c++  java
  • webapi文档描述Swagger使用

          1.创建webapi项目解决方案

      2.引用swagger nuget包

    3.项目属性生成xml.

    4.为了控制器和action 都有注释,我们创建一个Swagger-Custom.js 和SwaggerControllerDescProvider.cs 文件

     1 using Swashbuckle.Swagger;
     2 using System;
     3 using System.Collections.Concurrent;
     4 using System.Collections.Generic;
     5 using System.IO;
     6 using System.Linq;
     7 using System.Web;
     8 using System.Xml;
     9 
    10 namespace WMS.Server.App_Start
    11 {
    12    /// <summary>
    13     /// swagger显示控制器的描述
    14     /// </summary>
    15     public class SwaggerControllerDescProvider : ISwaggerProvider
    16     {
    17         private readonly ISwaggerProvider _swaggerProvider;
    18         private static ConcurrentDictionary<string, SwaggerDocument> _cache =new ConcurrentDictionary<string, SwaggerDocument>();
    19         private readonly string _xml;
    20         /// <summary>
    21         /// 
    22         /// </summary>
    23         /// <param name="swaggerProvider"></param>
    24         /// <param name="xml">xml文档路径</param>
    25         public SwaggerControllerDescProvider(ISwaggerProvider swaggerProvider,string xml)
    26         {
    27             _swaggerProvider = swaggerProvider;
    28             _xml = xml;
    29         }
    30 
    31         public SwaggerDocument GetSwagger(string rootUrl, string apiVersion)
    32         {
    33 
    34             var cacheKey = string.Format("{0}_{1}", rootUrl, apiVersion);
    35             SwaggerDocument srcDoc = null;
    36             //只读取一次
    37             if (!_cache.TryGetValue(cacheKey, out srcDoc))
    38             {
    39                 srcDoc = _swaggerProvider.GetSwagger(rootUrl, apiVersion);
    40 
    41                 srcDoc.vendorExtensions = new Dictionary<string, object> { { "ControllerDesc", GetControllerDesc() } };
    42                 _cache.TryAdd(cacheKey, srcDoc);
    43             }
    44             return srcDoc;
    45         }
    46 
    47         /// <summary>
    48         /// 从API文档中读取控制器描述
    49         /// </summary>
    50         /// <returns>所有控制器描述</returns>
    51         public  ConcurrentDictionary<string, string> GetControllerDesc()
    52         {
    53             string xmlpath = _xml;
    54             ConcurrentDictionary<string, string> controllerDescDict = new ConcurrentDictionary<string, string>();
    55             if (File.Exists(xmlpath))
    56             {
    57                 XmlDocument xmldoc = new XmlDocument();
    58                 xmldoc.Load(xmlpath);
    59                 string type = string.Empty, path = string.Empty, controllerName = string.Empty;
    60 
    61                 string[] arrPath;
    62                 int length = -1, cCount = "Controller".Length;
    63                 XmlNode summaryNode = null;
    64                 foreach (XmlNode node in xmldoc.SelectNodes("//member"))
    65                 {
    66                     type = node.Attributes["name"].Value;
    67                     if (type.StartsWith("T:"))
    68                     {
    69                         //控制器
    70                         arrPath = type.Split('.');
    71                         length = arrPath.Length;
    72                         controllerName = arrPath[length - 1];
    73                         if (controllerName.EndsWith("Controller"))
    74                         {
    75                             //获取控制器注释
    76                             summaryNode = node.SelectSingleNode("summary");
    77                             string key = controllerName.Remove(controllerName.Length - cCount, cCount);
    78                             if (summaryNode != null && !string.IsNullOrEmpty(summaryNode.InnerText) && !controllerDescDict.ContainsKey(key))
    79                             {
    80                                 controllerDescDict.TryAdd(key, summaryNode.InnerText.Trim());
    81                             }
    82                         }
    83                     }
    84                 }
    85             }
    86             return controllerDescDict;
    87         }
    88     }
    89 }
    View Code
    ///    <summary>
    /// 中文转换
    ///    </summary>
    var SwaggerTranslator = (function () {
        //定时执行检测是否转换成中文,最多执行500次  即500*50/1000=25s
        var 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 class="controller-summary" 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-250px;text-align:right;cursor:default;} </style>');
                $("#logo").html("接口描述").attr("href", "/Home/Index");
                //设置控制器描述
                _setControllerSummary();
                _translator2Cn();
            }
        }
        })();
    //执行转换
    SwaggerTranslator.Translator();
    

     

    5.打开 SwaggerConfig文件,注入XML.等描述

     public class SwaggerConfig
        {
            public static void Register()
            {
                var thisAssembly = typeof(SwaggerConfig).Assembly;
    
                GlobalConfiguration.Configuration
                    .EnableSwagger(c =>
                        {
                            
                            c.SingleApiVersion("v1", "SwaggerDemo"); 
    
                            c.IncludeXmlComments(GetXmlCommentsPath());//显示action注释
                            //显示控制器注释
                          c.CustomProvider((defaultProvider) => new SwaggerControllerDescProvider(defaultProvider, GetXmlCommentsPath())); 
                           
                        })
                    .EnableSwaggerUi("doc/{*assetPath}", b => b.InjectJavaScript(Assembly.GetExecutingAssembly(), "SwaggerDemo.Scripts.Swagger-Custom.js"));//注入自定义的js文件
            }
            private static string GetXmlCommentsPath()
            {
                return System.String.Format(@"{0}binSwaggerDemo.XML", System.AppDomain.CurrentDomain.BaseDirectory);
            }
        }
    View Code

     6.生成运行报错时:

    需要在配置文件设置指定版本7

    <runtime>
    		<assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
        
            <dependentAssembly>
              <assemblyIdentity name="Newtonsoft.Json" culture="neutral" publicKeyToken="30ad4fe6b2a6aeed" />
              <bindingRedirect oldVersion="0.0.0.0-7.0.0.0" newVersion="7.0.0.0" />
            </dependentAssembly>
           	</runtime>
    
    风雨之后见彩虹
  • 相关阅读:
    Pascal's Triangle II
    Pascal's Triangle
    Best Time to Buy and Sell Stock II
    Best Time to Buy and Sell Stock
    Populating Next Right Pointers in Each Node
    path sum II
    Path Sum
    [转载]小波时频图
    [转载]小波时频图
    [转载]Hilbert变换及谱分析
  • 原文地址:https://www.cnblogs.com/kingvi/p/11313917.html
Copyright © 2011-2022 走看看