為 ASP.NET Web API 建立說明頁面

發行項
09/27/2024

本教學課程包含程式碼，展示如何在 ASP.NET 4.x 中為 ASP.NET Web API 建立說明頁面。

當您建立 Web API 時，建立說明頁面通常很有用，以便其他開發人員知道如何呼叫您的 API。您可以手動建立所有文件，但最好盡可能自動產生。為了讓此任務變得更容易，ASP.NET Web API 提供了一個用於在執行時間自動產生說明頁面的程式庫。

ASP dot NET API 說明頁面的螢幕擷取畫面，顯示可供選擇的可用 API 產品及其說明。

建立 API 說明頁面

安裝 ASP.NET 和 Web Tools 2012.2 更新。此更新將說明頁面整合到 Web API 專案範本中。

接下來，建立一個新的 ASP.NET MVC 4 專案並選擇 Web API 專案範本。專案範本會建立一個名為 ValuesController 的範例 API 控制器。該範本還會建立 API 說明頁面。說明頁面的所有程式碼檔案都放置在專案的 Areas 資料夾中。

Web API 專案範本的功能表選項的螢幕擷取畫面，圈出了區域和說明頁面資料夾。

執行應用程式時，首頁包含指向 API 說明頁面的連結。從首頁，相關路徑是 /Help。

首頁的螢幕擷取畫面，指向可點擊的 API 字母，這些字母將打開說明頁面的連結。

此連結會將您帶到 API 摘要頁面。

API 摘要說明頁面的螢幕擷取畫面，顯示了不同的 API 值及其描述。

此頁面的 MVC 檢視在 Areas/HelpPage/Views/Help/Index.cshtml 中定義。您可以編輯此頁面來修改版面、簡介、標題、樣式等。

該頁面的主要部分是一個 API 資料表，按控制器分組。資料表項目是使用 IApiExplorer 介面動態產生的。 (稍後我將詳細討論此介面。) 如果新增新的 API 控制器，該資料表會在執行階段自動更新。

「API」列列出了 HTTP 方法和相對 URI。「描述」資料行包含每個 API 的文件。最初，文件只是預留位置文字。在下一節中，我將示範如何從 XML 註解新增文件。

每個 API 都有一個連結，指向包含更詳細資訊的頁面，包括範例請求和回應主體。

其中一個 API 選擇值的螢幕擷取畫面，顯示回應資訊和回應本文格式。

將說明頁面新增至現有項目

您可以使用 NuGet 套件管理員為現有 Web API 專案新增說明頁面。當您從與「Web API」範本不同的專案範本開始時，這個選項會非常實用。

從「工具」功能表中，選擇「NuGet 套件管理員」，然後選擇「套件管理員主控台」。在「套件管理員主控台」視窗中，鍵入下列其中一個命令：

對於 C# 應用程式：Install-Package Microsoft.AspNet.WebApi.HelpPage

對於 Visual Basic 應用程式：Install-Package Microsoft.AspNet.WebApi.HelpPage.VB

有兩種套件，一種用於 C#，一種用於 Visual Basic。確保使用與您專案相符的產品。

此命令安裝必要的組件並新增說明頁面的 MVC 檢視 (位於 Areas/HelpPage 資料夾中)。您需要手動新增指向說明頁面的連結。 URI 是 /Help。要在 Razor 檢視中建立連結，請新增以下內容：

@Html.ActionLink("API", "Index", "Help", new { area = "" }, null)

另外，請確保註冊區域。在 Global.asax 檔案中，將下列程式碼新增至 Application_Start 方法 (如果尚不存在) ：

protected void Application_Start()
{
    // Add this code, if not present.
    AreaRegistration.RegisterAllAreas();

    // ...
}

新增 API 文件

預設情況下，說明頁面會使用預留位置字串作為文件內容。您可以使用 XML 文件註解來建立文件。若要啟用此功能，請開啟檔案 Areas/HelpPage/App_Start/HelpPageConfig.cs 並取消註解下列行：

config.SetDocumentationProvider(new XmlDocumentationProvider(
    HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml")));

現在啟用 XML 文件。在「方案總管」中，以滑鼠右鍵按一下該專案並選擇「屬性」。選擇建置頁面。

方案總管視窗中專案下拉式功能表的螢幕擷取畫面，其中醒目顯示了建置選項。

在「輸出」下，檢查 XML 文件檔案。在編輯方塊中，鍵入 "App_Data/XmlDocument.xml"。

「輸出」對話方塊的螢幕擷取畫面，顯示輸出路徑和選擇 XML 文件檔案的選項。

接下來，開啟 ValuesController API 控制器的程式碼，程式碼在 /Controllers/ValuesController.cs 中定義。在控制器方法中新增一些文件註解。例如：

/// <summary>
/// Gets some very important data from the server.
/// </summary>
public IEnumerable<string> Get()
{
    return new string[] { "value1", "value2" };
}

/// <summary>
/// Looks up some data by ID.
/// </summary>
/// <param name="id">The ID of the data.</param>
public string Get(int id)
{
    return "value";
}

注意

提示：如果將插入符號放在方法上方的行上並鍵入三個正斜線，Visual Studio 會自動插入 XML 元素。然後您可以填寫空白部分。

現在再次建立並運行應用程式，然後瀏覽到說明頁面。文件字串應出現在 API 表中。

說明頁面中 API 表的螢幕擷取畫面，顯示 API 值和描述中的文件字串。

說明頁面在運行階段從 XML 檔案讀取字串。 (部署應用程式時，請確保部署 XML 檔案。)

深入探討

說明頁面建立在 ApiExplorer 類別之上，該類別是 Web API 架構的一部分。 ApiExplorer 類別提供了建立說明頁面的原始資料。對於每個 API，ApiExplorer 都包含一個描述 API 的 ApiDescription。為此，「API」會定義為 HTTP 方法和相對 URI 的組合。例如，以下是一些不同的 API：

GET /api/Products
GET /api/Products/{id}
POST /api/Products

如果控制器操作支援多個 HTTP 方法，則 ApiExplorer 會將每個方法視為不同的 API。

若要對 ApiExplorer 隱藏 API，請將 ApiExplorerSettings 屬性新增至動作，並將 IgnoreApi 設為 True。

[ApiExplorerSettings(IgnoreApi=true)]
public HttpResponseMessage Get(int id) {  }

您也可以將此屬性新增至控制器，以排除整個控制器。

ApiExplorer 類別會從 IDocumentationProvider 介面取得文件字串。正如您之前所看到的，說明頁面庫提供了一個 IDocumentationProvider，它可以從 XML 文件字串取得文件。程式碼位於 /Areas/HelpPage/XmlDocumentationProvider.cs 中。您可以透過編寫自己的 IDocumentationProvider 從其他來源取得文件。若要連接它，請呼叫 HelpPageConfigurationExtensions 中定義的 SetDocumentationProvider 擴充方法

ApiExplorer 會自動呼叫 IDocumentationProvider 介面來取得每個 API 的文件字串。它會將其儲存在 ApiDescription 和 ApiParameterDescription 物件的 Documentation 屬性中。

後續步驟

此處顯示的說明頁面並非全部。事實上，ApiExplorer 不僅限於建立說明頁面。 Yao Huang Lin 寫了一些很棒的部落格文章，可以幫助您開闊思路：

共用方式為