目的

每次要使用swaggerUI時候範例總是各式各樣，千奇百怪，下列範例是使用官方預設的Swashbuckle套件來教學。

建立新專案

選擇ASP.NET Core Web API專案範本，並執行下一步 步驟一

設定新的專案

命名你的專案名稱，並選擇專案要存放的位置。 步驟二

其他資訊

選擇.net6版本，支援OpenAPI支援一定要勾選，此選項.net5以後才會有，.net core 3.1並沒有此選項，需要從NuGet安裝，並點建立 步驟三

專案基本設定

右邊紅框處專案檔點兩下，會開啟專案的xml檔案，額外加入兩行xml資料，目的是要透過編譯器產生文件檔案

<GenerateDocumentationFile>true</GenerateDocumentationFile>
<NoWarn>$(NoWarn);1591</NoWarn>
  • 加入前 步驟4-1
  • 加入後 步驟4-2

編輯Program.cs檔案

修改program檔案內容，調整AddSwaggerGen的內容，目的是為了可以讀取我們所寫的註解 program檔案與.net5以前不一樣，保哥的部落格有比較詳細的說明

builder.Services.AddSwaggerGen(options => {
  // using System.Reflection;
  var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
  options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename));
});
  • 加入前 步驟5-1
  • 加入後 步驟5-2

編輯WeatherForecastController檔案

這裡有個重點，如果要增加下一個action時候，預設的範例檔案，需要調整route的設定，才能讀取到，不然會跳錯誤訊息

  • 加入前 步驟6-1
  • 加入後 步驟6-2 加入第二個方法 步驟6-3

執行結果

就可以成功讀取到兩個方法了 步驟6-4

參考

微軟官方

範例檔

GitHub