.NET Core 2.2 版本使用Swagger Core 版本初探

寫在前面

在全新的.NET Core 版本中我們熟悉的Swagger也迎來了全新的Core版本，在這裏我將記錄下搭建並完善Swagger的全部過程，其中有部分內容參考了相關資料在此附上鍊接。https://www.cnblogs.com/RayWang/p/9216820.html

準備工作

1. 創建一個.NET Core WebApi 項目
2. 創建一個Model類庫
3. 在WebApi中引入Swashbuckle.AspNetCore

正式開始

基礎建設：

1.在WebApi項目中執行命令：Install-package Swashbuckle.AspNetCore

2.在StarUp.cs的ConfigureServices中添加代碼

#region Swagger
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Info
                {
                    Version = "v1.1.0",
                    Title = "QMFrameWork WebAPI",
                    Description = "啓夢框架",
                    TermsOfService = "None",
                    Contact = new Swashbuckle.AspNetCore.Swagger.Contact { Name = "QMFrameWork", Email = "[email protected]", Url = "https://blog.csdn.net/weixin_42550800" }
                });
#endregion

3. 在StarUp.cs的Configure中添加代碼

#region Swagger
app.UseSwagger();
app.UseSwaggerUI(c =>
{
  c.SwaggerEndpoint("/swagger/v1/swagger.json", "ApiHelp V1");
});
#endregion

4.運行後進入/swagger目錄 即可查看Swagger已經啓用

5.如果需要將WebApi的默認啓動頁設爲Swagger則在Properties中

完善工作1，完善註釋配置 

在這裏大家會發現運行後接口的註釋並沒有顯示，我們需要配置註釋XML文件

1.首先在WebAPI項目上點擊右鍵-》屬性-》生成-》XML文檔文件

2.在StartUp中Swagger配置加入XML文件

 #region Swagger
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Info
                {
                    Version = "v1.1.0",
                    Title = "QMFrameWork WebAPI",
                    Description = "啓夢框架",
                    TermsOfService = "None",
                    Contact = new Swashbuckle.AspNetCore.Swagger.Contact { Name = "QMFrameWork", Email = "[email protected]", Url = "https://blog.csdn.net/weixin_42550800" }
                });
                // 爲 Swagger JSON and UI設置xml文檔註釋路徑
                var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//獲取應用程序所在目錄（絕對，不受工作目錄影響，建議採用此方法獲取路徑）
                //添加接口XML的路徑
                var xmlPath = Path.Combine(basePath, "TrySwaggerCore.xml");
                //如果需要顯示控制器註釋只需將第二個參數設置爲true
                c.IncludeXmlComments(xmlPath, true);
            });
            #endregion

3.運行後Swagger中就有了相關注釋

4.此時大家會發現有了許多警告，強迫症患者看這裏，我們只需要在生成中強制過濾1591的警告即可

5.切記此處代碼第二個參數需要設置爲True，否則將不顯示控制器級別的註釋，只顯示接口註釋

完善2，當註釋存在於其它項目實體時我們無法查看其它實體的註釋

現在很多時候我們需要用到倉儲模式對模型進行封裝，所以我們需要對某些存在於其它項目的實體進行註釋時應該怎麼辦呢？

以此項目爲例，我需要使用的實體處於Model中，則我們需要在Model的屬性-》生成-》XML文件中添加一個XML文件，注意保證該文件目錄在WebAPI中而不是Model中之後在StartUp中添加以下代碼

#region Swagger
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Info
                {
                    Version = "v1.1.0",
                    Title = "QMFrameWork WebAPI",
                    Description = "啓夢框架",
                    TermsOfService = "None",
                    Contact = new Swashbuckle.AspNetCore.Swagger.Contact { Name = "QMFrameWork", Email = "[email protected]", Url = "https://blog.csdn.net/weixin_42550800" }
                });
                // 爲 Swagger JSON and UI設置xml文檔註釋路徑
                var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//獲取應用程序所在目錄（絕對，不受工作目錄影響，建議採用此方法獲取路徑）
                //添加接口XML的路徑
                var xmlPath = Path.Combine(basePath, "TrySwaggerCore.xml");
                //定義實體類XML的路徑
                var entityXmlPath = Path.Combine(basePath, "Model.xml");
                //如果需要顯示控制器註釋只需將第二個參數設置爲true
                c.IncludeXmlComments(xmlPath, true);
                //添加實體的註釋
                c.IncludeXmlComments(entityXmlPath);
            });
            #endregion

        }

至此一個較爲完善的Swagger Core就搭建完成了