2024-10-29 019_讓summary註解顯示在 Swagger 中

發表於 分類於 閱讀次數：
2024-10-29 019_讓summary註解顯示在 Swagger 中

2024-10-29 019_讓summary註解顯示在 Swagger 中

要讓 summary 註解顯示在 Swagger 中，請確保以下步驟已正確設定：

  1. 確保在專案中安裝並設定了 Swagger：
    首先，確認你已經在 Startup.cs 或 Program.cs 中正確地設置了 Swagger，如下所示：
1
2
3
4
5
6
7
8
9
10
public void ConfigureServices(IServiceCollection services)
{
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "LogisticsAPI", Version = "v1" });
        c.IncludeXmlComments(GetXmlCommentsPath()); // 確保 XML 註解被包含
    });

    services.AddControllers();
}

  1. 生成 XML 註解文件：
    你需要讓項目生成 XML 註解文件，這樣 Swagger 才能讀取 summary 註解。

    • 右鍵點擊專案名稱 -> 選擇 “屬性” -> 點擊 “生成”。
    • 找到 “輸出” 區域，勾選 “XML 文件檔案” 並設置文件名稱和位置，例如：bin\Debug\net5.0\LogisticsAPI.xml。

    在 Program.cs 或 Startup.cs 中，添加對該 XML 文件的引用：

1
2
3
4
5
6
7
8
9
10
11
12
public void ConfigureServices(IServiceCollection services)
{
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "LogisticsAPI", Version = "v1" });
        var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
        var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
        c.IncludeXmlComments(xmlPath);  // 這會引入XML註解
    });

    services.AddControllers();
}

  1. 確認生成 XML 文件：
    確保專案在編譯時生成了 XML 文件，並且該文件路徑正確設置在 Swagger 的設定中。

  2. 檢查 Swagger UI：
    啟動應用程式，然後打開 Swagger 頁面，通常是：

    1
    https://localhost:{port}/swagger/index.html

    如果設定正確，你應該能看到 summary 註解，像是 “獲取所有包裹” 這段描述。

透過上述步驟，應該可以解決你的問題，讓 Swagger 顯示出 API 的 summary 註解。如果還是無法顯示，可以嘗試重新編譯專案，並確認 Swagger 正常讀取 XML
註解。

你的 Swagger 設置已經包含了 SwaggerDoc 和 IncludeXmlComments，同時也正確地添加了 JWT 身份驗證設置。這部分設置讓 Swagger 能夠顯示 API 文檔並支持 JWT 身份驗證。

為了讓 summary 和 XML 註解顯示正常，你可以確認以下幾件事：

  1. 確保 XML 文件路徑正確：
    IncludeXmlComments(GetXmlCommentsPath()) 中的 GetXmlCommentsPath() 方法應返回你所生成的 XML 文件路徑。你可以手動檢查此路徑：

    1
    2
    3
    4
    5
    private string GetXmlCommentsPath()
    {
        var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
        return Path.Combine(AppContext.BaseDirectory, xmlFile);
    }

    此方法應返回生成的 XML 文件路徑，確保該路徑對應的是你專案中生成的 XML 文件。

  2. 檢查生成 XML 文件：
    在專案的 Properties -> Build 中，檢查 “XML 文件” 的輸出選項是否正確設置，並確認它指向了正確的路徑（通常在 bin\Debug\net5.0 或對應版本的路徑中）。

  3. JWT 身份驗證設置確認：
    你的 JWT 驗證設置已經配置完畢。當你調用 API 時，請在 Swagger 中提供正確的 Bearer Token，這樣 Swagger 會自動將 JWT token 放入 Authorization header 中。這段設置正確地為 Swagger 文檔增加了身份驗證功能。

  4. 重新編譯並運行應用程序：
    完成這些設置後，重新編譯應用程式並啟動。訪問 Swagger UI，查看 API 的文檔是否正確顯示注解。URL 應類似於：

    1
    https://localhost:{port}/swagger/index.html

確認這些步驟後，summary 註解應該會正確顯示在 Swagger 中，並且 API 會支持 JWT 授權驗證。

看起來你的 Visual Studio 設定面板與傳統版本稍有不同。你可以在 **”建置”**（Build）選項中進行 XML 註解文件的設置。請按照以下步驟來啟用 XML 註解生成：

1. 在 “建置” 設置 XML 文件生成

  1. 在專案屬性頁面中，點擊 **”建置”**。

  2. 在建置頁面中，往下滾動查看是否有一個 “輸出”（Output）選項。

  3. 如果有，勾選 **”XML documentation file”**，並指定路徑，例如：

    1
    bin\Debug\net8.0\LogisticsAPI.xml

2. 如果在建置選項中找不到 XML 文件生成的選項

如果你在 Visual Studio 的建置選項中找不到設置 XML 文件生成的選項，建議你手動編輯專案的 .csproj 文件，進行如下操作：

  1. 找到專案的 .csproj 文件，通常位於專案的根目錄下（例如 LogisticsAPI.csproj）。

  2. 編輯 .csproj 文件，加入以下內容來啟用 XML 文件生成：

    1
    2
    3
    4
    <PropertyGroup>
      <GenerateDocumentationFile>true</GenerateDocumentationFile>
      <DocumentationFile>bin\Debug\net8.0\LogisticsAPI.xml</DocumentationFile>
    </PropertyGroup>

  3. 儲存 .csproj 文件，並重新編譯專案。

3. 檢查 XML 文件是否生成

重新編譯專案後，檢查 bin\Debug\net8.0\ 目錄下是否生成了 LogisticsAPI.xml 文件。這樣你的 Swagger 應該可以正常載入 XML 註解。

這些步驟應該能夠幫助你解決 XML 文件生成的問題，讓 Swagger 顯示正確的 API 註解。