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 註解。