ASP.NET Core Swagger UI 的設定

April 24, 2024

ASP.NET

Swagger UI 可以產生互動式的 API 的說明文件，列出 API 的說明、使用的模型，以及發送請求。這篇文章專注於 .Net 6 的 Swagger UI 設定，包含「專案文件設定」、「自訂 Request Header」兩個部份。

專案文件設定

如果方案底下有兩個或以上的專案，要把所有的專案的說明加入至 Swagger UI 內，需要增加以下兩行至每個專案的 csproj 檔案，放置於 PropertyGroup 標籤內：

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn> <!-- 這個屬性可以設定要壓制的警告，如果有其它需壓制的警告，也一起加進去 -->
</PropertyGroup>

CS1591 的警告，是告知已啟用產生註解的 XML 文件，但是卻沒有為每個成員和類別建立註解。

這樣專案在建置時會產生 {專案名稱}.xml 的檔案，需要在 Program.cs 內的 AddSwaggerGen 方法加入 XML 檔案：

builder.Services.AddSwaggerGen(c =>
{
    c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, "Project.xml")); // 需替換成專案名稱.xml
    // 其它 Swagger UI 設定
}

自訂 Request Header

如果今天 API 的設計包含額外的 Header，例如請求來源、語系、Token 等，想要在 Swagger 內加入這些自訂的 Header 的話，可以用以下的方式新增：

1. 建立一個實作 IOperationFilter 的類別，包含 Apply 方法。

2. Apply 方法內填入以下的程式碼：

public void Apply(OpenApiOperation operation, OperationFilterContext context)
{
    if(operation.Parameters == null) {
        operation.Parameters = new List<OpenApiParameter>();
    }

    operation.Parameters.Add(new OpenApiParameter
    {
        Name = "Source", // 參數名稱
        In = ParameterLocation.Header, // 除了標頭以外，也能放在 Path, QueryString ... 等
        Schema = new OpenApiSchema { Type = "string" }, // 參數資料型態
        Description = "請求來源", // 參數說明
        Required = true // 必須輸入
    }) ;
}

3. 在 AddSwaggerGen  方法內加入 c.OperationFilter<HeaderFilter>() ：

builder.Services.AddSwaggerGen(c =>
{
    c.OperationFilter<HeaderFilter>()
    // 其它 Swagger UI 設定
}

在 Swagger UI 上就會出現輸入額外 Header 的欄位 ~

參考資料