Asp.Net Core Api 使用Swagger管理文檔教程的安裝與使用

       這周因為公司的需求需要我做一個Api的程序，這周的三天時間我一直在Core Api和 framework Api之間做糾結。不知道要使用哪一個去做項目，想着想着就決定了。既然兩個我都沒用過那個何不來使用Core Api來做呢。也是對自己的一種鍛煉！

       OK，接下來回歸正題！

      Core下的Swagger和傳統framework  Mvc下的Swagger是不一樣的！

       兩者的差距：

      其一：引用的程序集不一樣。

         其二：安裝完程序集后需要配置的地方不一樣，

                            framework  下的Swagger安裝完后會有swaggerconfig和swaggernet這連個文件。它也是在這兩個文件下做配置。

                            Core 的安裝完成以后沒有這兩個文件，它的配置是在Core項目里Startup文件里做配置！

        開始安裝Swagger：

       對你的Api項目找到NuGet管理包，然后搜索“Swashbuckle.AspNetCore”。找到下面圖片中的程序包然后安裝即可！

       

           安裝完成后會在你的程序包里顯示出來！（如下圖所示）

            

          接下來就是配置的問題了，在Startup.cs文件中做配置

           

 

首先先引入如下命名空間：

using Swashbuckle.AspNetCore.Swagger;

將 Swagger 生成器添加到 Startup.ConfigureServices 方法中的服務集合中：（這個是簡短版的，后續我們在往里添加具體的更多的內容）

//注冊Swagger生成器，定義一個和多個Swagger 文檔
services.AddSwaggerGen(c =>
{
     c.SwaggerDoc("EHHD", new Info { Title = "EHHD", Version = "接口文檔" });
});

在 Startup.Configure 方法中，啟用中間件為生成的 JSON 文檔和 Swagger UI 提供服務：

  // 配置Swagger  必須加在app.UseMvc前面
            app.UseSwagger();
            //Swagger Core需要配置的  必須加在app.UseMvc前面
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/EHHD/swagger.json", "EHHDAPI");
            });

這樣啟動項目，在網站的localhost端口號后面加上Swagger就可以瀏覽Api文檔了。但是這樣的文檔沒有注釋。 添加注釋需要做一下的操作！

啟用XML 注釋：

• 右鍵單擊“解決方案資源管理器”中的項目，然后選擇“屬性”
• 查看“生成”選項卡的“輸出”部分下的“XML 文檔文件”框    （注意下圖中紅色框框標記的XML文件名，待會需要用到！）

       

   

 注意：

​ 1.對於 Linux 或非 Windows 操作系統，文件名和路徑區分大小寫。 例如，“SwaggerDemo.xml”文件在 Windows 上有效，但在 CentOS 上無效。

​ 2.獲取應用程序路徑，建議采用Path.GetDirectoryName(typeof(Program).Assembly.Location)這種方式或者·AppContext.BaseDirectory這樣來獲取

 3.要想有注釋需要添加的代碼在下面的代碼的注釋里有，就是最下面的三個代碼。第二行的XML文件名注意對應你自己項目的XML文件名！

 

  //Swagger所需要的配置項
            services.AddSwaggerGen(c =>
            {
                //添加Swagger.
                c.SwaggerDoc("EHHD", new Info
                {
                    Version = "EHHD",
                    Title = "醫患互動接口文檔",
                    Description = "This EHHD Api",
                    //服務條款
                    TermsOfService = "None",
                    //作者信息
                    Contact = new Contact
                    {
                        Name = "Sir_博",
                        Email = string.Empty,
                        Url = "http://www.cnblogs.com/Scholars/"
                    },
                    //許可證
                    License = new License
                    {
                        Name = "許可證名字",
                        Url = "http://www.cnblogs.com/Scholars/"
                    }
                });
                // 下面三個方法為 Swagger JSON and UI設置xml文檔注釋路徑
                var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//獲取應用程序所在目錄（絕對，不受工作目錄影響，建議采用此方法獲取路徑）
                var xmlPath = Path.Combine(basePath, "EHHD_Api.xml");
                c.IncludeXmlComments(xmlPath);
            });

            //讀取aoosettings.json里配置的數據庫連接語句需要的代碼
            services.Configure<DBContext>(Configuration.GetSection("SqlConfiguration"));
        }

 

這樣整個Swagger的Api文檔已經搭建完成了，我們來看看效果！

 

      但有一個問題就是每次運行項目都徐璈自己在頁面的端口號后面手動輸入Swagger這樣的路徑。讓人很苦惱，那我們就來配置一下讓它自動取到Swagger的Api頁面！

         展開項目的Properties下拉，打開launchSettings.json。對下圖中的練個箭頭標記的地方改成swagger就可以了！