使用 XML 註解和註釋擴充 OpenAPI 文件

已完成

Swagger UI 讓您不需要存取原始程式碼，就能與 API 資源互動，並以視覺化方式呈現。 API 的圖形表示法是從 OpenAPI 規格自動產生，方便其他開發人員建置取用 API 的應用程式。

Swagger UI 會以視覺化方式清楚呈現作業與方法，如下圖所示。

Swagger UI 也可讓您與每個作業互動，甚至一一試用。

使用 Swashbuckle 和 Swagger 工具自動建立 API 文件，可協助協力廠商了解您的 API 資源。 但若您想要再進一步深入，提供更為詳細的資訊，該怎麼做？ 如果您是初次使用 API，自然希望資訊越多越好。

XML 註解

您可以加入 XML 註解，為程式碼建立文件。 這些註解通常會直接放在要加上註解的程式碼區塊前面。

/// <summary>
/// Returns a group of Employees matching the given first and last names.
/// </summary>
/// <remarks>
/// Here is a sample remarks placeholder.
/// </remarks>
/// <param name="firstName">The first name to search for</param>
/// <param name="lastName">The last name to search for</param>
/// <returns>A string status</returns>
[HttpGet]
[Route("byname/{firstName}/{lastName}")]
public ActionResult<string> GetByName(string firstName, string lastName)
{
    return "Found another University employee";
}

會用到的 XML 節點如下：

• 摘要：以高階摘要列出方法/類別/欄位的性質或用途。
• 備註：方法/類別/欄位的更多詳細資料。
• 參數：方法中用到的參數，以及參數代表的意義。
• 傳回：說明方法所傳回的結果。

啟用 XML 註解之後，Swashbuckle 工具可以在 OpenAPI 文件中包含您的 XML 文件註解，並可讓您在 Swagger UI 中檢視。

資料註解

資料註解也是一樣。 只要將註釋新增到模型，Swagger 就會擴充 API 文件以將它納入。

舉例來說，如果您將下列註釋新增到控制器：

[Produces("application/json")]

...您會在 Swagger UI 中看到以下新增資訊：

提示

說明 API 時，有數種資料註解可運用。

• 辨識您的 API 在要求和回應上處理的是哪一種 content-types。 下列屬性會指定 API 只應雙向使用 application/json 內容類型。

  [Produces("application/json")]
  [Consumes("application/json")]
  

• 識別可能傳回給呼叫用戶端的潛在 HTTP 回應碼。 下列屬性所說明的 API 可能會傳回「404 找不到」。

  [ProducesResponseType(StatusCodes.Status404NotFound)]
  

  您的 API 可能會產生一組標準的回應碼，在此情況下，您可以使用下列屬性來指定 200、400 和 404，而不必個別指定。 深入瞭解如何使用 Web API 慣例。

  [ApiConventionMethod(typeof(DefaultApiConventions))]
  

• 產生 operationId 可大幅改善 API 使用量體驗，包括文件、程式碼產生，以及與其他服務整合。 您可以在 HTTP 動詞命令篩選條件中加入 Name 屬性，藉此自動產生 operationId。

  [HttpGet("{Height}/{Width}", Name="GetPrice")]