ASP.NET Core中使用Swagger

在實際的軟件開發過程中，我們通常會采用一種前后端分離的開發模式，在這種模式下一般會由前后端兩類開發人員協同開發，在這種情況下后端開發人員則需要提供API文檔去與前端人員進行對接，這樣才能保障后續的工作能夠順利開展。

 

並且當前項目在與外部系統進行業務往來或者數據交互的時候，我們通常會作為“接口方”對外提供數據，這種情況下我們通常也會需要后端開發人員去針對接口編寫API文檔。另外，在API接口開發完成后，我們的測試人員還要單獨下載第三方接口測試工具對API接口進行測試。

 

那么基於以上的應用場景的痛點，本文將推薦一個既方便又美觀的接口文檔框架——Swagger。

使用 Swagger 后，項目可以直接通過API代碼生成文檔，不再需要自己手動編寫接口文檔，對開發者來說非常方便，以此便可節約寫文檔的時間去產出更多的東西。不光如此，Swagger 還提供 Web 頁面，可在線測試 API的共，參數和格式都定好了，直接在界面上輸入對應的值，即可在線測試接口。

---

 1.使用Swagger

通常在項目中引用Swagger組件有兩種方式：一種是直接在網上下載到對應的類庫文件，另一種是通過NuGet包進行添加。下面主要介紹如何通過NuGet進行引用。

 

1.1.引用程序集

針對要引用的項目按鼠標右鍵，在彈出的菜單中單擊“管理NuGet程序包”，此時會彈出一個管理界面，然后在界面中切換到“瀏覽”選項卡頁，在搜索欄中搜索“Swashbuckle.Asp.NetCore”，然后選中搜索到的結果，在右側單擊“安裝”按鈕。

在安裝之后我們可以通過右側的“解決方案資源管理器”中查看項目對應的依賴項是否已經包含Swagger的包，並且通過下方的輸出窗口中看到，已經成功引入了6個程序集文件：

 

 1.2.配置Swagger服務

打開Startup.cs類，找到ConfigureServices方法，添加配置Swagger服務的代碼：

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
    
    #region 配置Swagger服務
        services.AddSwaggerGen(c =>
                               {
                                   c.SwaggerDoc("v1", new OpenApiInfo
                                                {
                                                    Version = "v1.0",
                                                    Title = "SwaggerShow",
                                                    Description = "接口說明文檔",
                                                    Contact = new OpenApiContact { Name = "張三", Email = "[e-mail]" }
                                                    
                                                }); ; //END SwaggerDoc()
                                   
                               }); // END AddSwaggerGen() 
    #endregion
        
        }

1.3.配置中間件

在Startup.cs類的Configure方法中，配置兩個中間件分別是：UseSwagger和UseSwaggerUI

   public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }

            #region 配置Swagger中間件
            app.UseSwagger();
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("swagger/v1/swagger.json", "v1");
            }); 
            #endregion

            app.UseRouting();

            app.UseAuthorization();

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
            });
        }

1.4.查看效果

在配置好Swagger的服務和中間件后，我們就可以啟動項目，然后在瀏覽器中輸入此格式的URL：IP:端口號/swagger，按下回車便可以看到Swagger界面了。

---

 2.接口文檔配置為項目首頁

通常我們的項目啟動會訪問默認的登錄頁或首頁，但在開發和測試的過程中，我們為了方便可以將Swagger接口文檔設置為我們項目的首頁(啟動頁)，這個時候我們就不必在瀏覽器中單獨輸入“/swagger”的標識了。方式如下：

 

1.將“launchSetting.json”文件中的“launchUrl”屬性刪除。

 2.在Startup.cs類的Configure方法中找到UseSwaggerUI的配置，並對其加入一個RoutePrefix屬性，將其賦值為空字符。

 

---

 3.Swagger中的接口添加注釋

要為接口添加注釋信息首先要找到接口對應的控制器(Controller)，並直接在控制器(Controller)中對控制器類或方法添加注釋信息即可。

 

添加玩注釋信息之后，接下來就需要把注釋信息在Swagger中展示。Swagger中接口對應的注釋信息是通過一個XML文件進行維護的。

因此我們需要對項目配置一個用於存儲Swagger接口注釋信息的XML文件，方法如下：

1. 在解決資源管理器中找到web項目，通過鼠標右擊的菜單中打開“屬性”界面。
2. 在“屬性”界面左側欄點擊“生成”，在“生成”下找到“輸出”。
3. 勾選“輸出”板塊下的“文檔文件”復選框。（這里演示的環境是VS2022，在其他VS中勾選“XML文檔文件”）。
4. 勾選后會彈出文本框讓你選擇一個XML文件的生成路徑，如果使用默認位置，可不填寫路徑。如果要自定義填寫，推薦填寫相對路徑。

在配置XML文檔文件后，則還需要在Startup類的ConfigureServices方法中，對Swagger服務配置部分，增加對XML文件的引用代碼，修改后的代碼如下：

   public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();

            #region 配置Swagger服務
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new OpenApiInfo
                {
                    Version = "v1.0",
                    Title = "SwaggerShow",
                    Description = "接口說明文檔",
                    Contact = new OpenApiContact { Name = "張三", Email = "[e-mail]" }

                }); ; //END SwaggerDoc()

                var basePath = AppContext.BaseDirectory;
                var xmlPath = Path.Combine(basePath, "SwaggerShow.xml");
                c.IncludeXmlComments(xmlPath, true);

            }); // END AddSwaggerGen() 
            #endregion

        }

修改代碼之后，啟動項目就可以看到接口相應的注釋信息了。

---

4.對Swagger中的Model添加注釋

作為一個標准化的接口文檔，只針對接口部分添加注釋信息肯定是不夠的，我們還需要為接口所涉及到的“Model”添加注釋。具體的實現也很簡單，大致和上面添加接口注釋信息的方式相同，這里不在過多使用圖例展示，而只是通過文字進行描述：

1. 為實體類Model添加注釋信息。
2. 仿照上面添加接口注釋的方式，為“Model實體類”所在項目（模型層）配置添加一個XML文檔文件。
3. 仿照上面添加接口注釋的方式，在ConfigureServices方法中對Swagger的服務配置增加對XML文件的引用代碼。

  public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();

            #region 配置Swagger服務
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new OpenApiInfo
                {
                    Version = "v1.0",
                    Title = "SwaggerShow",
                    Description = "接口說明文檔",
                    Contact = new OpenApiContact { Name = "張三", Email = "[e-mail]" }

                }); ; //END SwaggerDoc()

                var basePath = AppContext.BaseDirectory;
                var xmlPath = Path.Combine(basePath, "SwaggerShow.xml");
                c.IncludeXmlComments(xmlPath, true); //接口注釋信息                       
                c.IncludeXmlComments(Path.Combine(basePath, "SwaggerModel.xml"), true); //Model注釋信息

            }); // END AddSwaggerGen() 
            #endregion

        }

添加完成之后的效果如圖：

 

---

 5.去掉Swagger警告提示

我們在為Swagger中的接口或Model添加注釋信息后，會有一個現象：那就是項目下的所有類型或成員，都出現警告提示要求添加注釋信息。

如果不想添加注釋，又不想看到這個警告提示，可以這樣做：在項目中單擊鼠標右鍵，選擇“屬性”命令，然后在彈出的窗口中找到“生成”下的“錯誤和警告”，並在其下的“取消顯示警告”的文本框中添加“;1591”，然后重新生成項目即可。

---

6.忽略API

在我們的接口中可能存在一些不想對外公開的接口或接口的某個方法，對於這種情況我們可以在接口對於的Controller上或者Action上，增加特性“[ApiExploreSettings(IgnoreAPI)]”進行忽略，添加后對應的方法或接口就不會出現在Swagger文檔中了。