使用swagger實現web api線上介面文檔

一、前言

　　通常我們的項目會包含許多對外的介面，這些介面都需要文檔化，標準的介面描述文檔需要描述介面的地址、參數、返回值、備註等等；像我們以前的做法是寫在word/excel，通常是按模塊劃分，例如一個模塊包含n個介面，就形成一個文檔，然後再用版本控制管理。這樣做的缺點是：

1.不夠直觀，每次打開文檔查看介面很麻煩

2.文檔的維護難度大

3.調用方和測試人員使用麻煩，需要先去找介面，在用相應的工具測試（例如使用瀏覽器還可能要安裝插件）

　　我們希望是可以直接線上瀏覽，然後直接用瀏覽器測試。而介面的詳細描述都在程式里用註釋完成。swagger就可以完成這個工作（ps好像很多開發人員都還不知道這個東西。。。）。

二、使用Swagger

　　Swagger 是一款RESTFUL介面的文檔線上自動生成+功能測試功能軟體。

　　在web api 使用swagger可以說非常簡單，不需要編寫任何代碼，完全依賴於插件。具體步驟如下：

　   1.新建一個web api項目

　　2.使用nuget添加Swashbuckle包

　　3.完成

　　沒錯，就是這麼簡單！運行項目，轉到地址 http://localhost:57700/swagger/ui/index 會看到如下頁面，這是預設添加的兩個apicontroller：　　

　　這個時候介面還沒有具體的描述信息等，例如我們給ValuesController.Get添加註釋描述，在頁面上還是沒有顯示出來。需要按照如下步驟實現：

　　1. 在app_start 下 SwaggerConfig 大100行的位置找到 //c.IncludeXmlComments(GetXmlCommentsPath()); 如下註釋，改為：c.IncludeXmlComments(GetXmlCommentsPath(thisAssembly.GetName().Name)); （註意去掉註釋了）

　　2. 在SwaggerConfig添加一個方法代碼：

        protected static string GetXmlCommentsPath(string name)
        {
            return string.Format(@"{0}\bin\{1}.XML", AppDomain.CurrentDomain.BaseDirectory, name);
        }

　　3. 修改項目生成，在bin下對應的xml文件可以看到具體的描述文檔，如下：

　　重新生成項目，就要可以看到完整的介面描述了。例如我們心中一個TestController如下：

    /// <summary>
    /// 測試控制器
    /// </summary>
    public class TestController : ApiController
    {
        /// <summary>
        /// 測試Get方法
        /// </summary>
        /// <remarks>測試Get方法</remarks>
        /// <returns></returns>
        [HttpGet]
        public string Get()
        {
            return "Get";
        }

        /// <summary>
        /// 測試Post方法
        /// </summary>
        /// <param name="name">姓名</param>
        /// <param name="age">年齡</param>
        /// <remarks>測試Post方法</remarks>
        /// <returns></returns>
        [HttpPost]
        public string Post(string name, int age)
        {
            return name + age.ToString();
        }
    }

　　生成的頁面如下，可以看到介面的描述，點擊Try it out 即可調用：

三、非依賴代碼

　　上面的方式依賴於Swashbuckle包，它已經包含了Swagger-UI組件。我們的代碼需要引入這個包，實際上也可以不需要在項目中引入，單獨部署Swagger,包括Swagger-Ui（api展示） 和 Swagger-Editor（線上編輯器），它需要依賴nodejs環境，所以需要先按照nodejs。部署其實也很簡單，例如這是我部署的結果：

　　swagger-editor:　　

　　swagger-ui:

　　編輯後只需要將文件保存為json文件，然後拷貝到指定的目錄即可。這個部署也非常簡單，具體可以參照：

　　1.http://www.raye.wang/2016/09/29/swaggerhuan-jing-da-jian-zhi-fei-yi-lai-dai-ma-fa/?utm_source=tuicool&utm_medium=referral

　　2.http://blog.csdn.net/ron03129596/article/details/53559803

四、總結

　　規範化api的編寫和註釋，以及標準化文檔，對於團隊的開發效率有很大的提升，也有利於項目的維護。例如使用線上介面文檔後，測試人員測試只需要在頁面輸入參數，點擊調用就可以看到調用結果。

　　swagger 也有線上版的，不需要要自己部署。實際上非代碼依賴的方式反而更麻煩，使用代碼依賴的方法可以像平時我們寫註釋一樣就可以，既能在程式里描述，方便開發人員瞭解介面功能，也可以在線上展示，發佈調用方和測試人員調用。