一.未使用Swagger狀況

　　相信無論是前端開發人員還是後端開發人員，都或多或少都被介面文件折磨過，前端經常抱怨後端給的介面文件或與實際情況不一致。後端又覺得編寫及維護介面文件會耗費不少精力，經常來不及更新。 其實無論是前端呼叫後端，還是後端呼叫後端，都期望有一個好的介面文件。但是這個介面文件對於程式設計師來說，就跟註釋一樣，經常會抱怨別人寫的程式碼沒有寫註釋，然而自己寫起程式碼起來，最討厭的，也是寫註釋。 所以僅僅只通過強制來規範大家是不夠的，隨著時間推移，版本迭代，介面文件往往很容易就跟不上程式碼了

　二.使用Swagger狀況

　　Swagger 提供了一個視覺化的UI頁面展示描述檔案，其中包括介面的呼叫，介面所需引數（header,body,url.params），介面說明，引數說明等。介面的呼叫方、測試、專案經理等都可以在該頁面中對相關介面進行查閱和做一些簡單的介面請求。只要在專案框架搭建時，對Swagger 進行了配置，後面持續迭代的時候，只會花很小代價去維護程式碼、介面文件以及Swagger描述檔案。因為一旦介面發生改變，程式重新部署，介面文件會重新生成對應新的文件。

　三.如何使用？

　　在NetCore專案中怎麼去使用Swagger來生成介面文件呢？

　　首先在 webApi 啟動專案 上 右鍵 點選管理Nuget程式包， 安裝  Swashbuckle.AspNetCore ，然後到  Startup 中新增引用  using Swashbuckle.AspNetCore.Swagger; 

　　在ConfigureServices方法中新增以下程式碼

            #region Swagger

            services.AddSwaggerGen(options =>
            {
                options.SwaggerDoc("v1", new Info
                {
                    Version = "v1",
                    Title = "API Doc",
                    Description = "作者:Levy_w_Wang",
                    //服務條款
                    TermsOfService = "None",
                    //作者資訊
                    Contact = new Contact
                    {
                        Name = "levy",
                        Email = "[email protected]",
                        Url = "https://www.cnblogs.com/levywang"
                    },
                    //許可證
                    License = new License
                    {
                        Name = "tim",
                        Url = "https://www.cnblogs.com/levywang"
                    }
                });

                #region XmlComments

                var basePath1 = Path.GetDirectoryName(typeof(Program).Assembly.Location);//獲取應用程式所在目錄（絕對，不受工作目錄(平臺)影響，建議採用此方法獲取路徑）
                //獲取目錄下的XML檔案 顯示註釋等資訊
                var xmlComments = Directory.GetFiles(basePath1, "*.xml", SearchOption.AllDirectories).ToList();

                foreach (var xmlComment in xmlComments)
                {
                    options.IncludeXmlComments(xmlComment);
                }
                #endregion

                options.DocInclusionPredicate((docName, description) => true);

                options.IgnoreObsoleteProperties();//忽略 有Obsolete 屬性的方法
                options.IgnoreObsoleteActions();
                options.DescribeAllEnumsAsStrings();
            });
            #endregion

上面寫的迴圈是因為專案中可能有多個控制器類庫，為的是排除這種情況

接下來，再到 Configure 方法中新增：

            #region Swagger

            app.UseSwagger(c => { c.RouteTemplate = "apidoc/{documentName}/swagger.json"; });
            app.UseSwaggerUI(c =>
            {
                c.RoutePrefix = "apidoc";
                c.SwaggerEndpoint("v1/swagger.json", "ContentCenter API V1");
                c.DocExpansion(DocExpansion.Full);//預設文件展開方式
            });

            #endregion

這裡使用了 RoutePrefix  屬性，為的是改變原始開啟介面文件目錄，原始路徑為 swagger/index.html ,現在為 /apidoc/index.html 

這個時候在需要輸出註釋的控制器類庫的屬性 中設定如下資訊，並新增上相關注釋

然後執行起來，開啟本地地址加上  /apidoc/index.html  就可以看到效果，

特別提醒：如果開啟下面這個介面能正常顯示，但是提示  Fetch errorInternal Server Error v1/swagger.json  錯誤，說明有方法未指明請求方式，如 HttpGet HttpPost HttpPut 等，找到並指明，重新執行就正常了

  點選方法右上角的 Try it out ，試下呼叫介面，然後點選Exectue,執行檢視結果，能得到後端方法返回結果就說明成功。

特別說明：有介面不需要展示出去的時候，可以在方法上新增屬性 Obsolete ，這樣就不會顯示出來。 前提：有前面ConfigureServices中 後面的 忽略 有Obsolete 屬性的方法 設定才行！！！

 最後可以看到介面返回資料正常，並且也能看到介面響應請求嘛等等資訊，一個介面應該返回的資訊也都有顯示。

總結：

本文從為開發人員手寫api文件的痛楚，從而引申出Swagger根據程式碼自動生成出文檔和註釋，

並且還可以將不需要的方法不顯示等設定。然後進行了簡單的測試使用 。

但是！！一般後端方法都有token等驗證，需要在header中新增token、sid等欄位來驗證使用者，保障安全性，

該設定將在下一章節中寫！

以上若有什麼不對或可以改進的地方，望各位指出或提出意見，一起探討學習~

有需要原始碼的可通過此 GitHub 連結拉取 覺得還可以的給個 start 和點個 下方的推薦哦~~謝謝！