使用Swagger實現webapi介面自動化文件生成

weixin_34391854發表於2017-06-26
SwaggerWebAPI

         這裡是實現自動化api穩當的生成，在網上看了很多swagger的文件，可能都是在為實現介面時直接使用的swagger，其實步驟差不多，但是更加詳細的我還沒看到，又或者說，我看著文件來的時候還是出錯啦，繞了很大的彎，之前有聽過要用這個，但是還是用過。接下來總結下我這次在使用過程中的步驟及一些問題。

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

         一、在現有Api的基礎上新增Nuget包的引用（這裡簡述下現有api，不一定是webapi專案，要看介面實現在哪裡，可以是類庫，也可以是專案webapi等），有2個包，一個是Swagger.Net.UI，一個是Swashbuckle，如下圖所示：

          （1）、Swagger.Net.UI的新增引用：

          

          （2）、Swashbuckled的新增引用

          

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

 

          二、安裝成功後會有新增的檔案如下所示：

                                               

             上面的因為前端的ui等都整合在dll中，所以SwaggerUI、App_Start下的SwaggerNet類都可以刪除 ，然後主要是配置SwaggerConfig.cs檔案。      

 

           三、在設定的啟動專案下生成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類中，如下圖所示：

              

             最後一步就是在我們不需要顯示的介面類或者類內方法上面新增如下過濾器如下：

                           

 

            五、修改App_Start資料夾下的SwaggerNet檔案，註釋如下圖的程式碼（我不知道為什麼，如果不註釋會報錯的）：

              

               註釋程式碼如下：

              

             以上就是實現自動化的全部步驟，在位址列中輸入地址如下：即可看到如下的介面：

              

                過程就是這樣的，可是做個小demo練習，我這個是直接在專案中新增啦。

相關文章