從零開始搭建前后端分離的NetCore2.2（EF Core CodeFirst+Autofac）+Vue的項目框架之十一Swagger使用一

本文轉載自查看原文 2019-11-22 14:58 921 Swagger/ NetCore

　一.未使用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 = "levy_w_wang@qq.com",
                        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