使用Swashbuckle構建RESTful風格文檔

　　本次和大家分享的是Swagger to WebApi的nuget包Swashbuckle；因為項目需要統一api文檔的風格，並要支持多種開發語言（C#，java，python），所以首先想到的是swagger來構建api文檔，本章講解的是對.net的webpi來生成文檔，后續會將java的springmvc+swagger來構建接口文檔。

• 准備工作
• 快速構建簡易api文檔
• swagger文檔支持在header中增加Token參數

. 准備工作

　　首先創webapi項目，然后通過nuget管理器安裝Swashbuckle的包，我這里通過console命令安裝：

　　 Install-Package Swashbuckle -Version 5.6.0 

　　注意只需要安裝這個包就行了，其他的會自動引用，由於Swashbuckle包含了swagger的引用，所以不用再單獨操作引用了。

. 快速構建簡易api文檔

　　如上安裝完Swashbuckle后其實就能夠直接運行看效果了，我這里的訪問路徑是： http://localhost:51847/swagger/ui/index ，注意：/swagger/ui/index 是默認固定的路徑，這是nuget包封裝的路徑，訪問后能看到如下界面效果：

　　

　　一個簡易的文檔就弄好了，swagger的顏色看起來搭配不錯；由於大多數接口都是post請求方式，因此咋們以/api/values的post接口為例如：

　　

　　對於接口文檔而言，上面文檔存在如下一些疏漏：

• 未說明方法的功能
• 參數屬性的描述沒有
• 返回屬性的描述沒有

　　為了方便其他人員對接接口，所以對接口文檔我們需要增加一些描述，要增加描述這里就要知曉：Swashbuckle是通過xml文件來讀取配置信息的，該xml文件里面包含了我們在代碼中對方法，對類，對參數，對返回值做的文字描述；首先定義一個請求和響應的實體 如：

/// <summary>
    /// 登錄請求
    /// </summary>
    public class MoLoginRq
    {
        /// <summary>
        /// 賬號
        /// </summary>
        public string UserName { get; set; }
        /// <summary>
        /// 密碼
        /// </summary>
        public string UserPwd { get; set; }
    }

    /// <summary>
    /// 登錄返回
    /// </summary>
    public class MoLoginRp
    {
        /// <summary>
        /// 登錄返回的token
        /// </summary>
        public string Token { get; set; }
    }

　　新增一個登錄接口，代碼如：

/// <summary>
        /// 登錄接口
        /// </summary>
        /// <param name="rq">請求</param>
        /// <returns>響應</returns>
        [HttpPost]
        public MoLoginRp Login(MoLoginRq rq)
        {
            MoLoginRp rp = new MoLoginRp();

            rp.Token = Guid.NewGuid().ToString();

            return rp;
        }

　　到這里基本的動作都做完了，剩下的是上面我們說的xml文件怎么來，又怎么和swagger關聯；

　　首先，看項目的App_Start文件夾里面應該在安裝nuget包的時候會自動增加一個 SwaggerConfig.cs 文件，里面就是swagger使用的一些設置，我們需要找到被注釋的： //c.IncludeXmlComments(GetXmlCommentsPath()); 代碼，取消注釋並創建一個 GetXmlCommentsPath() 方法（獲取xml注釋文件路徑） 如：

public static string GetXmlCommentsPath()
        {
            //D:/WebApplication/bin/WebApplication.xml
            return Path.Combine(
                AppDomain.CurrentDomain.BaseDirectory,
                "bin",
                string.Format("{0}.XML", typeof(SwaggerConfig).Assembly.GetName().Name));
        }

　　這個時候代碼基本完成了，還需要我們通過vs設置一下生成項目時自動創建xml文件，如下：鼠標右鍵起始項目-》屬性-》生成-》勾選xml文件

　　

　　然后，鼠標右鍵重新生成下項目，這個時候bin目錄就有了WebApplication.xml

　　

　　這個xml文件內容就是一些注釋的信息，具體各位自己點看看下xml內容；到這里我們設置和代碼都弄完了，來看下swagger頁面效果，通過預覽 http://localhost:51847/swagger/ui/index ：

　　

　　這個時候我們增加的一些文字說明就完成了，這個時候細心的朋友能夠看出來我們的Action方法名稱沒識別出來，這不符合我們命名規范，這里有兩種解決方案：

• 在action方法上增加 [ActionName("Login")] 標記
• 修改WebApiConfig.cs文件的路由如："api/{controller}/{action}/{id}"

　　這里我采用后者，為了統一通過方法名來識別對應接口：

　　

swagger文檔支持在header中增加Token參數

　　對於api接口，我們通常在登錄后的其他操作都會讓調用方傳遞授權的token，而token一般做法是放在請求的header里面，swagger文檔為了測試方便可以把token放在header作為參數傳遞；首先創建測試接口GetNames：

        /// <summary>
        /// 獲取用戶名稱列表
        /// </summary>
        /// <returns></returns>
        [HttpPost]
        public List<string> GetNames()
        {
            List<string> list = new List<string> {"神牛001","神牛002", "神牛003" };

            return list;
        }

　　然后在App_Start/SwaggerConfig.cs文件中添加：

c.ApiKey("apiKey")
     .Description("授權token")
     .Name("token")
     .In("header");

　　並啟動：

EnableSwaggerUi(c =>
     {
          c.EnableApiKeySupport("token", "header");
    });

　　然后啟動並在swagger界面輸入：

　　

　　這個時候點擊try it out請求接口，能夠在看到請求里面包含了token信息：