【Cs】Core API Swagger

文前言

記一些 Swagger 相關的東西

主文

如何在 Swagger UI API 加上可填寫自訂 Header 欄位：

網路上給出不少範例如 [WEB API] Swagger - 在 Headers 中新增 API Token 驗證 ~ m@rcus 學習筆記，但都只有 Framework 的版本，因此紀錄

以下為向 Claude web 詢問後的解法：

using Microsoft.AspNetCore.Mvc.Controllers;
using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;
using System.Linq;

/// <summary>
/// Swagger 操作過濾器，用於在每個 API 的 Swagger 文件中自動加入 Header 中的 Token 參數說明。
/// 實作 <see cref="IOperationFilter"/> 介面，於 Swagger 產生文件時套用。
/// </summary>
public class HeaderTokenOperationFilter : IOperationFilter
{
    /// <summary>
    /// 對指定的 API 操作 (Operation) 加入 Token 參數定義，
    /// 使 Swagger UI 顯示該 API 需於 Header 帶入 Token 才能呼叫。
    /// </summary>
    /// <param name="operation">目前要產生 Swagger 文件的 API 操作物件，將對其 Parameters 集合進行新增。</param>
    /// <param name="context">
    /// 操作過濾器的上下文物件，包含 <see cref="ApiDescription"/>、
    /// <see cref="MethodInfo"/> 等資訊，可用於判斷是否需要針對特定 Action 套用此參數。
    /// </param>
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        if (operation.Parameters == null)
            operation.Parameters = new List<OpenApiParameter>();

        operation.Parameters.Add(new OpenApiParameter
        {
            Name = "Token",
            In = ParameterLocation.Header,
            Description = "User Token In Header",
            Required = true,
            Schema = new OpenApiSchema
            {
                Type = "string"
            }
        });
    }
}

然後調整

cs title:Program.cs builder.Services.AddSwaggerGen(options => { // Swagger UI 可顯示 header 欄位 options.OperationFilter<HeaderTokenOperationFilter>(); });

這樣就可以了！

放之前：

放之後：

UPDATE LOG

115. 07/22 開新篇