.Net Core 5.x Api開發筆記 -- Swagger設置Header(九)

Swagger的基礎使用可以參考之前的文章：.Net Core 5.x Api開發筆記 -- Swagger(七)

這裡只記錄如何給Swagger添加Header，要達到的效果如下圖所示：

1，添加 HttpHeaderFilter 參數設置類

在項目中添加一個參數設置類，命名自定義就行，如下圖所示：

代碼如下：

 1 public class HttpHeaderFilter : IOperationFilter
 2 {
 3     /// <summary>
 4     /// 給Swagger添加Header頭部參數
 5     /// </summary>
 6     /// <param name="operation"></param>
 7     /// <param name="context"></param>
 8     public void Apply(OpenApiOperation operation, OperationFilterContext context)
 9     {
10         operation.Parameters = new List<OpenApiParameter>
11         {
12             new OpenApiParameter
13             {
14                 Name = "token",
15                 Description = "Token",
16                 In = ParameterLocation.Header,
17                 Required = false
18             },
19             new OpenApiParameter
20             {
21                 Name = "TermID",
22                 Description = "學期ID",
23                 In = ParameterLocation.Header,
24                 Required = false
25             },
26             new OpenApiParameter
27             {
28                 Name = "ContainerID",
29                 Description = "組織ID",
30                 In = ParameterLocation.Header,
31                 Required = false
32             }
33         };
34     }
35 }

參數說明：

Name：就是設置header的欄位屬性名稱，在同一個參數位置，名稱必須唯一，且大小寫敏感。

In：參數位置，常見有三個：

• path：參數成為操作路徑（URL）的一部分，俗稱路徑參數。路徑參數的 required 欄位必需為 true
• query：參數成為操作路徑（URL）查詢參數的一部分，俗稱查詢參數，如/users?id=123456
• header：參數成為 HTTP 請求頭的一部分，俗稱請求頭參數。註意：請求頭是大小寫敏感的

Required：是否必需，預設值是 false

我們按照 In：參數位置的類型分別設置成 Header、Query、Path，看是什麼效果

2, 使用參數設置類 HttpHeaderFilter 

上邊的參數類已經創建好，下邊看下如何使用、使用很簡單，代碼如下(加紅標粗的代碼部分)

 1 public void ConfigureServices(IServiceCollection services)
 2 {
 3     services.AddControllers();
 4 
 5     //swagger
 6     services.AddSwaggerGen(options =>
 7     {
 8         options.SwaggerDoc("swaggerapi", new OpenApiInfo
 9         {
10             Version = "v1",
11             Title = "swaggerapi API文檔",
12             Description = "swaggerapi API的使用說明"
14         });
15 
16         // 為 Swagger JSON and UI設置xml文檔註釋路徑
17         // 獲取應用程式所在目錄（絕對路徑，不受工作目錄影響，建議採用此方法獲取路徑）
18         // 此方式適用於Windows/Linux 平臺
19         var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);
20         var xmlPath = Path.Combine(basePath, "NetCore.Swagger.xml");
21         options.IncludeXmlComments(xmlPath);
22 
23         //添加自定義header授權參數
24         options.OperationFilter<HttpHeaderFilter>(Array.Empty<object>());
25     });
26 }

完畢！！！