使用Swagger實現webapi接口自動化文檔生成

         這裏是實現自動化api妥當的生成，在網上看了不少swagger的文檔，可能都是在爲實現接口時直接使用的swagger，其實步驟差很少，可是更加詳細的我還沒看到，又或者說，我看着文檔來的時候仍是出錯啦，繞了很大的彎，以前有聽過要用這個，可是仍是用過。接下來總結下我此次在使用過程當中的步驟及一些問題。

        在接口已經成型的基礎上集成swagger，實現了接口文檔的自動化生成，相對於開發來講節約了寫文檔的大部分時間，無疑是一件莫大的好事情。接下來總結下這個過程：

         1、在現有Api的基礎上添加Nuget包的引用（這裏簡述下現有api，不必定是webapi項目，要看接口實如今哪裏，能夠是類庫，也能夠是項目webapi等），有2個包，一個是Swagger.Net.UI，一個是Swashbuckle，以下圖所示：

          （1）、Swagger.Net.UI的添加引用：

          

          （2）、Swashbuckled的添加引用

          

            這裏的版本是4.5.2的版本，可能在4.0版本上就不同啦，這裏我沒有嘗試。。。

 

          2、安裝成功後會有新增的文件以下所示：

                                               

             上面的由於前端的ui等都集成在dll中，因此SwaggerUI、App_Start下的SwaggerNet類均可以刪除 ，而後主要是配置SwaggerConfig.cs文件。      

 

           3、在設置的啓動項目下生成XML文件，步驟以下：

            例如：我目前項目中有去實現接口的web項目，我就選擇此「web項目」->「屬性」->「生成」->勾選XML文件文件，以下如所示：

            

           而後點擊保存，便可在bin文件下面找到此文件，能夠自行去看下。

 

            四、修改App_Start文件夾下的SwaggerConfig文件

             （1）、添加註釋

             打開App_Start文件夾下的SwaggerConfig文件，在方法Register把註釋過的c.IncludeXmlComments(GetXmlCommentsPath());放開，而後在此類中增長方法GetXmlCommentsPath來獲取生成文件的位置便可（又或者以下圖，直接取XML文件也可）。而下面的路徑是上面生成的XML文件的路徑，而放開註釋的那段代碼實現了對XMl文件的讀取，即添加註釋，方法的實現以下：

               

             （2）、隱藏不須要的接口（便可以添加劇復的接口）

             

             上面就是全部用到的，關於處理接口的代碼，c.DocumentFilter<HiddenApiFilter>();這個是爲了實現過濾本身不須要的接口來設置的

            HiddenApiFilter這個類的實現以下：

    /// <summary>  
    /// 隱藏接口，不生成到swagger文檔展現  
    /// </summary>  
    [System.AttributeUsage(System.AttributeTargets.Method | System.AttributeTargets.Class)]

    public partial class HiddenApiAttribute : System.Attribute { }
    public class HiddenApiFilter : IDocumentFilter
    {
        /// <summary>  
        /// 重寫Apply方法，移除隱藏接口的生成  
        /// </summary>  
        /// <param name="swaggerDoc">swagger文檔文件</param>  
        /// <param name="schemaRegistry"></param>  
        /// <param name="apiExplorer">api接口集合</param>  
        public void Apply(SwaggerDocument swaggerDoc, SchemaRegistry schemaRegistry, IApiExplorer apiExplorer)
        {
            foreach (ApiDescription apiDescription in apiExplorer.ApiDescriptions)
            {
                if (Enumerable.OfType<HiddenApiAttribute>(apiDescription.GetControllerAndActionAttributes<HiddenApiAttribute>()).Any())
                {
                    string key = "/" + apiDescription.RelativePath;
                    if (key.Contains("?"))
                    {
                        int idx = key.IndexOf("?", System.StringComparison.Ordinal);
                        key = key.Substring(0, idx);
                    }
                    swaggerDoc.paths.Remove(key);
                }
            }
        }

             這個類爲了方即可以直接在swaggerconfig類中，以下圖所示：

              

             最後一步就是在咱們不須要顯示的接口類或者類內方法上面添加以下過濾器以下：

                           

 

            5、修改App_Start文件夾下的SwaggerNet文件，註釋以下圖的代碼（我不知道爲何，若是不註釋會報錯的）：

              

               註釋代碼以下：

              

             以上就是實現自動化的所有步驟，在地址欄中輸入地址以下：便可看到以下的界面：

              

                過程就是這樣的，但是作個小demo練習，我這個是直接在項目中添加啦。