前言
今天想針對互動式的 API 文件，進行分享。開發時，常遇到需要先提供規格(request、response)，並可以直接在瀏覽器上測試 API 等需求，最早遇過團隊用 word 去編輯，後來發生了強大的套件可以處理掉這件事情，省去非常多時間，使我們專心在開發上，不是一些文件編輯上！

分享主軸

• 如何註冊與使用
• 了解 Swagger內詳細意思

安裝 Swashbuckle.AspNetCore 套件

註冊 Swagger

簡易版本

在program.cs 內添加服務與 Middleware

builder.Services.AddSwaggerGen();

app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
        c.RoutePrefix = "swagger";
    });

        /// <summary>
        /// 氣象預報
        /// </summary>
        [HttpGet(Name = "GetWeatherForecast")]
        public IEnumerable<WeatherForecast> Get()
        {
            return Enumerable.Range(1, 5).Select(index => new WeatherForecast
            {
                Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
                TemperatureC = Random.Shared.Next(-20, 55),
                Summary = Summaries[Random.Shared.Next(Summaries.Length)]
            })
            .ToArray();
        }

結果

詳細版本

• 可以自訂更詳細說明(每個方法規格，包括Request、Response回傳欄位、方法描述等等)
• 也可以設定不同版本的 API 規格文件，如下圖中右上下拉，比如前台、後台、V1.0、V2.0等等
• 若 header 需要放置 token 驗證，也可以在 Swagger UI 上設定

program.cs

    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);

    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "範例API規格文件",
        Version = "v1.0",
        Description = "專案各個模組詳細功能",
        Contact = new OpenApiContact
        {
            Name = "專案測試站台",
            Email = "test@gmail.com"
        }
    });

    var app = builder.Build();
    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
        c.RoutePrefix = "swagger";
        c.DocumentTitle = "專案方法文件";// 設置文檔標題
        c.DisplayRequestDuration(); // 顯示請求持續時間
        //c.EnableBasicAuth(); // 啟用基本認證
        c.ConfigObject.AdditionalItems["theme"] = "dark"; // 設置主題
        c.SupportedSubmitMethods(new[] { SubmitMethod.Get, SubmitMethod.Post, SubmitMethod.Put, SubmitMethod.Delete }); // 支持的提交方法
        c.ShowExtensions();
        c.ShowCommonExtensions();
    });

        /// <summary>
        /// 取得氣象預報
        /// </summary>
        /// <remarks>
        /// Sample request:
        ///
        ///     GET /WeatherForecast
        ///
        /// </remarks>
        /// <returns>氣象預報清單</returns>
        /// <response code="200">返回用戶信息</response>
        /// <response code="400">無效的用戶 ID</response>
        /// <response code="404">用戶未找到</response>
        [HttpGet]
        [ProducesResponseType(typeof(IEnumerable<WeatherForecast>), 200)]
        [ProducesResponseType(StatusCodes.Status400BadRequest)]
        [ProducesResponseType(StatusCodes.Status404NotFound)]
        public IActionResult GetWeatherForecast()
        {
            var weatherForecasts = Enumerable.Range(1, 5).Select(index => new WeatherForecast
            {
                Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
                TemperatureC = Random.Shared.Next(-20, 55),
                Summary = Summaries[Random.Shared.Next(Summaries.Length)]
            })
            .ToArray();

            return Ok(weatherForecasts);
        }

結果

• 上圖範例中 400 與 404 回傳的格式，使用 ApiController 屬性時，框架會自動處理一些常見的錯誤並返回標準化的錯誤格式。這個標準化的錯誤格式稱為 Problem Details，它遵循 RFC 7807 規範
  參考文章 : https://triozillion-rao.medium.com/net-problemdetails-fc5f625eb25c

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "additionalProp1": "string",
  "additionalProp2": "string",
  "additionalProp3": "string"
}

補充說明

• c.SwaggerDoc("v1", new OpenApiInfo { ... }): 定義一個新的 Swagger 文檔，版本為 "v1"
• Title = "範例API規格文件": 設置 API 文檔的標題
• Version = "v1.0": 設置 API 文檔的版本
• Description = "專案各個模組詳細功能": 設置 API 文檔的描述，說明專案的各個模組和功能
• Contact = new OpenApiContact { ... }: 設置聯絡信息
• Name = "專案測試站台": 聯絡人的名稱
• Email = "test@gmail.com": 聯絡人的電子郵件地址

• c.DocumentTitle = "專案方法文件" : 設置 Swagger UI 頁面的標題，這個標題將顯示在瀏覽器標籤頁上

• c.DisplayRequestDuration() : 啟用請求持續時間顯示，這樣可以在 Swagger UI 中顯示每個 API 請求的持續時間

• //c.EnableBasicAuth() : 啟用基本認證功能，要求用戶輸入用戶名和密碼來訪問 API

• c.ConfigObject.AdditionalItems["theme"] = "dark"
  設置 Swagger UI 的主題為 "dark"，這可以改變 Swagger UI 的外觀，使其使用深色主題

• c.SupportedSubmitMethods(new[] { SubmitMethod.Get, SubmitMethod.Post, SubmitMethod.Put, SubmitMethod.Delete })
  設置 Swagger UI 中支持的 HTTP 提交方法，這裡指定了 GET、POST、PUT 和 DELETE 方法

• c.ShowExtensions() : 啟用顯示 API 擴展資訊，這些擴展信息通常是一些自定義的資料

• c.ShowCommonExtensions() : 啟用顯示常見的 API 擴展資訊

要顯示詳細說明必須添加下列步驟(檢查是否已經設定)

1. 註冊 : ( 設定與取得 XML 文件檔案 )
   var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
   var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
   c.IncludeXmlComments(xmlPath);

2. 專案檔案內 -> 屬性 -> 建置 -> 輸出 -> 文件檔案 (這需要勾選)

除了上述這些，也可以自己寫一個 Middleware去封裝起來，讓 Program.cs內乾淨一點

簡單統整今日重點

• 了解Swagger用法 (簡單與進階)
• 了解 Swagger 設定上程式碼代表意思

今日結語

介紹如何設定與使用 Swagger 強大的文件套件，使用在 API 架構上，其實 MVC 也可以使用，做法都一樣
希望對大家有幫助，明日繼續努力 ~~ 加油 ！

參考文章

https://learn.microsoft.com/en-us/aspnet/core/tutorials/web-api-help-pages-using-swagger?view=aspnetcore-8.0

https://www.youtube.com/watch?v=lml_j5ujjeQ