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文檔注釋和漢化。