ASP.NET Core WebAPI幫助頁--Swagger簡單使用1.0

一、什麼是Swagger？

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

 

二、爲啥選用swagger?

1）它具備交互式文檔、客戶端SDK生成和API可發現性等優勢。

2）書寫api說明文檔的工具備不少，可是能稱之框架只有swagger

 

三、Swagger 規範 (swagger.json)

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

 

四、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

五、總結

經過本篇文章的簡單介紹，咱們能夠簡單瞭解到：

一、什麼是Swagger？

二、swagger的優勢。

三、ASP.NET Core 使用Swagger生成api說明文檔。

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

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

寫博客也是爲了督促本身學習和記錄學習的內容，最後感謝"老張的哲學"對於知識的分享,不少時候都是在他們這些前輩的基礎上去學習，下一次再分享關於swagger api文檔註釋和漢化。