最近工作上的變動，又開始拾起後端開發。

距離前面已經有兩年多了。也是幸好當時已經對 .NET Core 有了一些瞭解，並且也開始了一些專案。

當時主要是基於 .NET Core 2.1 的。對比起來還是有了不少變化的。

就拿Swagger來說，在 2.1 當時還沒有開源的庫可以直接引用的。

Swagger 作為一個規範和完整的框架，用於生成、描述、呼叫和視覺化 RESTful 風格的 Web 服務。

對比以前為了給前端介面呼叫文件，是一個個在 Postman 上面測試呼叫，有了 Swagger 方便了很多。配置好後，在寫程式碼時新增一些註釋就可以使用。

一、註冊

在註冊 Swagger 前，先要引用所需的包：

Swashbuckle.AspNetCore

Swashbuckle.AspNetCore.Filters

安裝完成後在 Startup.cs 檔案中新增如下程式碼

public void ConfigureServices(IServiceCollection services)
{
            services.AddSwaggerGen(c =>
            {
                // 定義文件（可以多個）
                c.SwaggerDoc("V1", new OpenApiInfo { Title = "Backend.WebAPI
 
", Version = "V1" });
                // 文件排序規則
                c.OrderActionsBy(o => o.RelativePath);
            });
}    

上面的程式碼是註冊了 Swagger 生成器。我們想在執行時看到對應介面的話還需要新增對應的 UI 中介軟體：

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

            // 插入中介軟體，將生成的 Swagger 公開為 JSON 端點
            app.UseSwagger();
            // 插入 swagger-ui 中介軟體，公開互動式文件
            // 呼叫是： ip/port/swagger/index.html
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/V1/swagger.json", "Backend.WebAPI V1");

                // 路徑配置，設定為空，直接在根域名下訪問，這時 launchSettings 下面的 launchUrl 配置也改為空
                c.RoutePrefix = "";
            });

        }

二、註釋資訊

上面的配置完成後雖然可以看到 Swagger 文件介面，但是對應的介面註釋都沒有，不利於檢視。

這時就需要對做兩部分內容。

1、專案配置生成註釋 xml 檔案

一般要生成的註釋主要有：介面、DTO

那就主要對著兩個專案設定：對應專案右鍵=》屬性=》生成 tab 頁

如下圖：

　　a、勾選“輸出”下的“XML文件檔案”，勾選後需要設定路徑，路徑使用“..\XXX\YYY”（..\是相對目錄，相對當前專案）

　　b、在“取消顯示告警”後面輸入框中新增：1591（用 ; 分隔）。不新增的話，多有當前專案下檔案都需要註釋，否則會有警告提示（根據個人喜好，我不喜歡有太多提示）

在當前解決方案中對需要的專案進行設定即可。

2、在程式碼中載入 xml 檔案

已經生成了 xml 檔案，需要在 Swagger 生成器中載入才可以在文件中看到，程式碼如下：

var basePath = ApplicationEnvironment.ApplicationBasePath;
services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("V1", new OpenApiInfo { Title = "Backend.WebAPI", Version = "V1" });
    c.OrderActionsBy(o => o.RelativePath);

    // 載入 Control 配置資訊
    var xmlPath = Path.Combine(basePath, "Backend.WebAPI.xml");
    c.IncludeXmlComments(xmlPath, true);

    // 載入 Model 配置資訊
    var xmlModelPath = Path.Combine(basePath, "Backend.Model.xml");
    c.IncludeXmlComments(xmlModelPath, true);
});

我這裡是添加了兩個 xml 檔案。

三、新增請求頭

在專案中，添加了授權認證後。在 Swagger 上面測試介面，那麼也需要帶上 token 之類的。

這是還需要對進行配置：

var basePath = ApplicationEnvironment.ApplicationBasePath;
// 註冊 Swagger 生成器，並定義文件（可以多個）
services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("V1", new OpenApiInfo { Title = "Backend.WebAPI", Version = "V1" });
    c.OrderActionsBy(o => o.RelativePath);

    // 載入 Control 配置資訊
    var xmlPath = Path.Combine(basePath, "Backend.WebAPI.xml");
    c.IncludeXmlComments(xmlPath, true);

    // 載入 Model 配置資訊
    var xmlModelPath = Path.Combine(basePath, "Backend.Model.xml");
    c.IncludeXmlComments(xmlModelPath, true);

    // 使用 Filter 擴充套件 Swagger 生成器
    // 沒有下面這幾個 Filter， Swagger 上無法攜帶 Bearer ，介面就一直報錯
    c.OperationFilter<AddResponseHeadersFilter>();
    c.OperationFilter<AppendAuthorizeToSummaryOperationFilter>();
    c.OperationFilter<SecurityRequirementsOperationFilter>();

    // Token 繫結到 ConfigureServices
    c.AddSecurityDefinition("oauth2", new OpenApiSecurityScheme
    {
        Description = "JWT 授權，在下框中輸入 Bearer {token}",
        Name = "Authorization",
        In = ParameterLocation.Header,
        Type = SecuritySchemeType.ApiKey
    });
});

配置完成後，在 Swagger UI 文件中會有需要輸入 Authorize 的按鈕。

整體配置完成後如下圖：