Swagger-UI展示接口

簡單介紹API的管理工具Swagger的UI模塊。

簡介：swagger ui就是一個能整合到項目中讓api的注釋能夠生成到一個網頁上。能簡單測試和給前端看。

第一步：添加引用

打開NuGet程序包管理器，搜索Swagger。安裝搜索出來的這個Swashbuckle。

 

第二步：修改配置文件

 安裝完成后會在根目錄App_Start文件夾下生成SwaggerConfig.cs。

打開此文件，按照西面配置即可，注意命名空間。

using System.Web.Http;
using WebActivatorEx;
using WebApplication1;
using Swashbuckle.Application;
using Swashbuckle.Swagger;
using System.Collections.Concurrent;
using System.Collections.Generic;
using System.IO;
using System.Xml;

[assembly: PreApplicationStartMethod(typeof(SwaggerConfig), "Register")]

namespace WebApplication1
{
    public class SwaggerConfig
    {
        public static void Register()
        {
            var thisAssembly = typeof(SwaggerConfig).Assembly;

            GlobalConfiguration.Configuration
                .EnableSwagger(c =>
                    {
                        c.SingleApiVersion("v1", "WebApplication1");
                        c.IncludeXmlComments(System.AppDomain.CurrentDomain.BaseDirectory + "/bin/WebApplication1.XML");
                        c.CustomProvider((defaultProvider) => new CachingSwaggerProvider(defaultProvider));
                    })
                .EnableSwaggerUi(c =>
                    {
                        c.InjectJavaScript(thisAssembly, "WebApplication1.Scripts.swagger.js");
                    });
        }
    }
    public class CachingSwaggerProvider : ISwaggerProvider
    {
        private static ConcurrentDictionary<string, SwaggerDocument> _cache = new ConcurrentDictionary<string, SwaggerDocument>();

        private readonly ISwaggerProvider _swaggerProvider;

        public CachingSwaggerProvider(ISwaggerProvider swaggerProvider)
        {
            _swaggerProvider = swaggerProvider;
        }

        public SwaggerDocument GetSwagger(string rootUrl, string apiVersion)
        {
            var cacheKey = string.Format("{0}_{1}", rootUrl, apiVersion);
            SwaggerDocument srcDoc = null;
            if (!_cache.TryGetValue(cacheKey, out srcDoc))
            {
                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/WebApplication1.XML", System.AppDomain.CurrentDomain.BaseDirectory);
            ConcurrentDictionary<string, string> dic = new ConcurrentDictionary<string, string>();
            if (!File.Exists(xmlpath))
            {
                return dic;
            }
            XmlDocument doc = new XmlDocument();
            doc.Load(xmlpath);
            XmlNodeList list = doc.SelectNodes("//member[contains(@name,'T:')]");
            foreach (XmlNode item in list)
            {
                string val = item.Attributes["name"].Value;
                string key = val.Substring(val.LastIndexOf('.') + 1).Replace("Controller", "");
                XmlNode node = item.FirstChild;
                if (!dic.ContainsKey(key))
                {
                    dic.TryAdd(key, node.InnerText.Trim());
                }
            }
            return dic;
        }
    }
}

 

第三步：修改項目的輸出XML文件

右鍵項目的屬性，生成，勾選

 

第四步：顯示控制器的別稱

需要自己創建第二步中需要的swagger.js文件。在項目的Scripts文件夾中添加名為swagger.js文件。內容如下：

$(function () {
    var init = function () {
        $.getJSON($("#input_baseUrl").val(), {}, function (res) {
            $("#resources_container .resource").each(function (i, item) {
                var _id = $(item).attr("id");
                if (!_id) { return; }
                var strSummary = res.ControllerDesc[_id.substring(9)];
                if (strSummary) {
                    $(item).children(".heading").children(".options").prepend('<li style="color:#000">' + strSummary + '</li>');
                }
            });
        });
    };
    init();
});

 

第五步：添加方法得特性標簽

        [HttpGet]
        [Route("api/values/GetMyName/id")]
        public string GetMyName(int id)
        {
            return "value";
        }

 

 

到這里所有步驟全部完成，接下來我們只需要運行項目。然后在地址欄中加上/swagger/ui/index.

http://localhost:port/swagger/ui/index

最后界面如下：

 

 

 

然后我們試一下是否成功。

點開這個方法界面如下，輸入參數，點擊try it out. 我們會得到接口返回的“value”字符串。測試配置成功！