1、什麼是Swagger？

Swagger是一個規範且完整的框架，提供描述、生產、消費和視覺化RESTful API，它是為了解決Web API生成有用文件和幫助頁的問題。

 

2、為啥選用swagger?

1）它具有互動式文件、客戶端SDK生成和API可發現性等優點。

2）書寫api說明文件的工具有很多，但是能稱之框架只有swagger

 

3、Swagger 規範 (swagger.json)

Swagger 流的核心是 Swagger 規範，預設情況下是名為 swagger.json 的文件。 它由 Swagger 工具鏈（或其第三方實現）根據你的服務生成。 它描述了 API 的功能以及使用 HTTP 對其進行訪問的方式。 它驅動 Swagger UI，並由工具鏈用來啟用發現和客戶端程式碼生成。

 

4、ASP.NET Core 使用Swagger生成api說明文件

4.1引用Nuget包，“Swashbuckle.AspNetCore”

Swashbuckle.AspNetCore 是一個開源專案，用於生成 ASP.NET Core Web API 的 Swagger 文件。 Swashbuckle 有三個主要組成部分：

• Swashbuckle.AspNetCore.Swagger：將 SwaggerDocument 物件公開為 JSON 終結點的 Swagger 物件模型和中介軟體。
• Swashbuckle.AspNetCore.SwaggerGen：從路由、控制器和模型直接生成 SwaggerDocument 物件的 Swagger 生成器。 它通常與 Swagger 終結點中介軟體結合，以自動公開 Swagger JSON。
• Swashbuckle.AspNetCore.SwaggerUI：Swagger UI 工具的嵌入式版本。 它解釋 Swagger JSON 以構建描述 Web API 功能的可自定義的豐富體驗。 它包括針對公共方法的內建測試工具。

4.2新增並配置Swagger中介軟體

在Startup.cs類中，編輯ConfigureServices方法 public void ConfigureServices(IServiceCollection services) { services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2); services.AddSwaggerGen(c => { c.SwaggerDoc("V1.0", new Swashbuckle.AspNetCore.Swagger.Info { Title = "My WebAPI", Description="API說明文件", Version = "V1.0", Contact=new Swashbuckle.AspNetCore.Swagger.Contact { Name="Blog.Core"} }); }); }

4.3在Startup.cs類中Configure 方法中，啟用中介軟體生成Json文件和SwaggerUI提供服務

public void Configure(IApplicationBuilder app, IHostingEnvironment env) { if (env.IsDevelopment()) { app.UseDeveloperExceptionPage(); } app.UseSwagger(); app.UseSwaggerUI(c => { c.SwaggerEndpoint("/swagger/v1/swagger.json", "My Web API"); }); app.UseMvc(); } 到此，已經完成Swagger的新增，啟動專案，在埠後面輸入/Swagger,然後回車，就可看到生成API文件效果了   注意：如果ConfigureServices 方法中的  services.AddSwaggerGen 註冊的一個名字 c.SwaggerDoc("v1.0"的V1.0, 和Configure 方法中的app.UseSwaggerUI(c => { c.SwaggerEndpoint("/swagger/v1/swagger.json", "My Web API"); })的V1不一致,將會出現下面的bug

5、總結

通過本篇文章的簡單介紹，我們可以簡單瞭解到：

1、什麼是Swagger？

2、swagger的優點。

3、ASP.NET Core 使用Swagger生成api說明文件。

4、ASP.NET Core使用Swagger中常遇到的錯誤

 原始碼已經放到Github上面，地址是：https://github.com/xiaoerhao/Blog.Core

寫部落格也是為了督促自己學習和記錄學習的內容，最後感謝"老張的哲學"對於知識的分享,很多時候都是在他們這些前輩的基礎上去學習，下一次再分享關於swagger api文件註釋和漢