使用swagger實現web api在線接口文檔

1、前言

　　一般咱們的項目會包含許多對外的接口，這些接口都須要文檔化，標準的接口描述文檔須要描述接口的地址、參數、返回值、備註等等；像咱們之前的作法是寫在word/excel，一般是按模塊劃分，例如一個模塊包含n個接口，就造成一個文檔，而後再用版本控制管理。這樣作的缺點是：

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

2.文檔的維護難度大

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

　　咱們但願是能夠直接在線瀏覽，而後直接用瀏覽器測試。而接口的詳細描述都在程序裏用註釋完成。swagger就能夠完成這個工做（ps好像不少開發人員都還不知道這個東西。。。）。

2、使用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 便可調用：

　　

3、非依賴代碼

　　上面的方式依賴於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

4、總結

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

　　swagger 也有在線版的，不須要要本身部署。實際上非代碼依賴的方式反而更麻煩，使用代碼依賴的方法能夠像平時咱們寫註釋同樣就能夠，既能在程序裏描述，方便開發人員瞭解接口功能，也能夠在在線展現，發佈調用方和測試人員調用。