2019年5月18日 星期六

ASP.NET Core 安裝 Swashbuckle 自動產生 API 說明文件檔案

目的:自動抓取註解產生下面的 API 說明文件網頁



























NuGet 安裝 Swashbuckle.AspNetCore


引用 Swashbuckle.AspNetCore.Swagger



using Swashbuckle.AspNetCore.Swagger;

設定 Startup.cs 的 ConfigureServices

public void ConfigureServices(IServiceCollection services)
{
 services.AddMvc();
 
 #region 註冊 Swagger
 // 註冊 Swagger
 services.AddSwaggerGen(c =>
 {
  c.SwaggerDoc(
   // name: 攸關 SwaggerDocument 的 URL 位置。
   name: "v1",
   // info: 是用於 SwaggerDocument 版本資訊的顯示(內容非必填)。
   info: new Info
   {
    Title = "標題",
    Version = "版本號 1.0.0",
    Description = "說明",
    TermsOfService = "無",
    Contact = new Contact
    {
     Name = "強尼 John Wu",
     Url = "https://blog.johnwu.cc"
    },
    License = new License
    {
     Name = "西西 CC BY-NC-SA 4.0",
     Url = "https://creativecommons.org/licenses/by-nc-sa/4.0/"
    }
   }
  );
  // 為 Swagger JSON and UI設置xml文檔註釋路徑
  var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//獲取應用程序所在目錄(絕對,不受工作目錄影響,建議採用此方法獲取路徑)
  var xmlPath = Path.Combine(basePath, "Swagger.xml");
  c.IncludeXmlComments(xmlPath);
 });
 #endregion 註冊 Swagger
}



點選「屬性」「建置」
新增「隱藏警告」1591
新增「XML 文件檔案」程式碼設定 Swagger.xml 這邊也填入 Swagger.xml



















設定 Startup.cs 的 Configure

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{

 #region 註冊 Swagger
 // 註冊 Swagger
 app.UseSwagger();
 app.UseSwaggerUI(c =>
 {
  c.SwaggerEndpoint(
   // url: 需配合 SwaggerDoc 的 name。 "/swagger/{SwaggerDoc name}/swagger.json"
   url: "/swagger/v1/swagger.json",
   // name: 用於 Swagger UI 右上角選擇不同版本的 SwaggerDocument 顯示名稱使用。
   name: "RESTful API v1.0.0"
  );
 });
 #endregion 註冊 Swagger

 app.UseMvc(routes =>
 {
  routes.MapRoute(name: "default", template: "{controller}/{action}/{id?}");
 });

}
   
程式開啟後,輸入網址 http://localhost:port/swagger
就能開啟 Swagger UI 網頁

























PS.在 Blazor 安裝 Swagger 後,
在 Ubuntu 上執行有異常(收不到封包),
最後換了 NSwag 才正常










沒有留言:

Visual Studio 2017/2019 推薦的擴充功能與更新

參考文章: 覺得 Google 的 Blogger 不太順手?透過 HTML 的 iframe 移花接木 HackMD