C#WebApi中swagger線上文檔輸出參數和輸入參數顯示注釋

標籤：lin   contains   body   類型   pts   空間名   gen   空間   lis   

 

 

最近開發webapi 時需要產生線上文檔，發現文檔裡面沒注釋，在網上尋找資料都不齊全，或者看起來很難看懂。

花了點時間搞出來了這個，很多都是借鑒網上資料整理的，通俗易懂小白專用。

最終效果如所示

1.定義一個SwaggerControllerDescProvider實現ISwaggerProvider介面

using Swashbuckle.Swagger;using System;using System.Collections.Concurrent;using System.Collections.Generic;using System.IO;using System.Linq;using System.Web;using System.Xml;namespace Nop.Web.App_Start{    /// <summary>    /// swagger顯示控制器的描述    /// </summary>    public class SwaggerControllerDescProvider : ISwaggerProvider    {        private readonly ISwaggerProvider _swaggerProvider;        private static ConcurrentDictionary<string, SwaggerDocument> _cache =new ConcurrentDictionary<string, SwaggerDocument>();        private readonly string _xml;        /// <summary>        ///         /// </summary>        /// <param name="swaggerProvider"></param>        /// <param name="xml">xml文檔路徑</param>        public SwaggerControllerDescProvider(ISwaggerProvider swaggerProvider,string xml)        {            _swaggerProvider = swaggerProvider;            _xml = xml;        }        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  ConcurrentDictionary<string, string> GetControllerDesc()        {            string xmlpath = _xml;            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;        }    }}

　　

2.定義一個JS檔案,做成嵌入資源，這個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 () {        $.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").first().prepend(‘<li class="controller-summary" title="‘ + strSummary + ‘">‘ + strSummary + ‘</li>‘);                        }                    }                });            }        });    },    _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": "應用",    "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();});

　　

3.修改App_Start中的SwaggerConfig.cs檔案，主要代碼有兩行

c.CustomProvider((defaultProvider) => new SwaggerControllerDescProvider(defaultProvider,xmlFile));

.EnableSwaggerUi(c => c.InjectJavaScript(thisAssembly, "Test.WebApi.Scripts.Swagger-Custom.js"));

Test.WebApi.Scripts.Swagger-Custom.js 這是我們在第二步中定義的資源檔，資源檔名的命名規則如下：檔案所在項目的命名空間.檔案徑路.檔案名稱

最終代碼如下

public static void Register()        {           var xmlFile = string.Format("{0}/bin/Test.WebApi.XML", System.AppDomain.CurrentDomain.BaseDirectory);            #region 原生配置            var thisAssembly = typeof(SwaggerConfig).Assembly;            GlobalConfiguration.Configuration                .EnableSwagger(c =>                    {                        c.IncludeXmlComments(GetXmlCommentsPath("Test.Model"));                        //                        c.SingleApiVersion("v1", "Test.WebApi").Description("content");                        //設定介面描述xml路徑地址                        c.IncludeXmlComments(xmlFile);                        //                        c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());                        // Wrap the default SwaggerGenerator with additional behavior (e.g. caching) or provide an                        // alternative implementation for ISwaggerProvider with the CustomProvider option.                        //                        c.CustomProvider((defaultProvider) => new InformationApp.WebApi.App_Start.SwaggerControllerDescProvider(defaultProvider, xmlFile));                        //                        c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());                    })                .EnableSwaggerUi( c =>                    {                        c.InjectJavaScript(thisAssembly, "Test.WebApi.Areas.SSO.Content.js.Swagger-Custom.js");                    });            #endregion        }        private static string GetXmlCommentsPath(string name)        {            return string.Format("{0}/bin/{1}.XML", System.AppDomain.CurrentDomain.BaseDirectory, name);        }

　　

千萬要注意的是

c.IncludeXmlComments(GetXmlCommentsPath("Test.Model"));

這裡面的參數Test.Model是介面輸入輸出參數的模型類所在的命名空間名稱

並且Test.Model這個類庫產生的時候還要設定產生xml出來

如所示，點擊Test.Model類庫右鍵屬性

勾選紅色框內的內容

不懂的東西多查查資料還是很有用的，感謝部落格上個的各個前輩寫下的心得

以上內容引用自

https://www.cnblogs.com/94pm/p/8046580.html

https://www.cnblogs.com/liangxiarong/p/7768431.html

我只是整理了一下，讓新手更容易看明白

C#WebApi中swagger線上文檔輸出參數和輸入參數顯示注釋