多專案(multiple projects)時，會產生多個 xml document, 叫用 IncludeXmlComments 時記得要把每個專案的 xml document 都載入，才能顯示不同專案中的註解和說明 (comment)。

範例如下:

builder.Services.AddSwaggerGen(options =>

{

    options.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });



    //多個 Project, 每一個 xmldocument 都要載入

    List<string> xmlFiles = Directory.GetFiles(AppContext.BaseDirectory, "*.xml", SearchOption.TopDirectoryOnly).ToList();

    foreach (string fileName in xmlFiles)

    {

        string xmlFilePath = Path.Combine(AppContext.BaseDirectory, fileName);

        if (File.Exists(xmlFilePath))

            options.IncludeXmlComments(xmlFilePath, includeControllerXmlComments: true);

    }



    //防止 SchemaId 的錯誤

    options.CustomSchemaIds(type => type.ToString());

}); 

這些都可以從註解中讀取:


 
 

 

每次在 swagger 中輸入的資料都會因為 Visual Stodio 在 compile 後，自動更新 Broswer 而被清除，實在很討厭。

在 Properties/launchSettings.json 中設定以下參數:

"hotReloadEnabled" : false

 

順帶一提，可以加一個設定 "launchBrowser": false ，這樣就不會一直開 Browser，可以加快速度。
 

 
在註冊Swagger時如圖中
1. 將各自action名稱代用不同編碼，避免名稱相撞導致swagger不能正確辨識。
2. 將專案XML輸出改為專案名稱($(AssemblyName))供註冊時指定反射用
↓ (對專案點擊右鍵 => 屬性 => 生成(Build) => 輸出(Output) => XML 文件名稱(XML documentation file path))
 
 

改用 NSwag 時直接 Copy 舊專案，發現找不到 AddOpenApiDocument 和 UseOpenApi 以及 UseSwaggerUi3 如下圖:

 
 

找了一些文件，要求安裝套件，都沒有用，後來發現在 Dependencies 的 Packages 直接新增 NSwag.AspNetCore 即可 





 
不要用 NuGet Package Manager 哦...

 
於VS Web中建立虛擬目錄，導致Swagger Handler出現重複錯誤
主要原因是因為跟網站與子網站指向同一個資料夾，而父子網站的web.config有繼承關係導致。

解決方式:
1. 前往 根目錄 / .vs / 專案 / config / applicationhost.config

2. 將site中設定的子網站移除或變更虛擬目錄位置

 
3. 回到網頁重新整理就完成囉!

參考: 【茶包射手日記】怪異的web.config HttpHandler重複錯誤

直接對 Action 參數傳入 IFormFile 物件會變成 Json 物件，要包在物件中才會正常 出現一個 file upload 如下圖












 

在 .Net Core 的專案使用 NSwag 時遇到: Unable to render this definition, The provided definition does not specify a valid version field. 錯誤. 有點一頭霧水, 最後解決了, 大概記錄一下解決的過程:




1. 把所有的 Controller 全部移. 再開啟 /swager, 此時應該會有空的 swager 頁面, 若異常, 則應該是 NSwag 沒裝好.

2. 把 Controller 一個一個加入專案, 每加入一個, 就開啟一次 /swager 的頁面, 若是發現異常, 就是那個 controller 有問題.

3. 找到有問題的 Controller 之後, 可以把內容先全部註解掉, 然後再一個一個的把 function 加回 controller, 應該就可以找到造成問題的 Action. 該問題有可能是以下情況造成:
    A. Action 沒有指定存取的 method.
    B. 不是 Action 的 function 被設定為 public (在 Controller 裡面, 非提供 client 端存取的 function, 都不應被設為 public)
    C. 這個很神奇, 註解也有可能造成問題, 試著把該 Action 的註解刪除, 再重新加入, 說不定就會好了.



 
另外, 使用 swagger 時, 要記得在專案的屬性的建置選項中, 要勾選 XML 註解輸出, 才會自動把  Action 的註解變成說明文字.: