介紹：
Swagger也稱為Open API，Swagger從API文檔中手動完成工作，並提供一系列用於生成，可視化和維護API文檔的解決方案。簡單的說就是一款讓你更好的書寫API文檔的框架。
我們為什么選擇swagger，現在的網站開發結果越來越注重前后端的分離，比如以前的webFrom到現在的mvc模式都是為了這個前后端的分離。就算再如何的分離實現，也是不可避免的要進行數據交互的，那么接口的重要性就提現出來了。他成了前端和后端交互的重要途徑，API文檔也因此成了前端開發人員與后端開發人員的重要紐帶。所有我們有一個API文檔框架豈不是美哉。
Swashbuckle有三個主要組件：
Swashbuckle.AspNetCore.Swagger：Swagger對象模型和中間件，將SwaggerDocument對象公開為JSON端點。
Swashbuckle.AspNetCore.SwaggerGen：一種Swagger生成器，可SwaggerDocument直接從路由，控制器和模型構建對象。它通常與Swagger端點中間件結合使用，以自動公開Swagger JSON。
Swashbuckle.AspNetCore.SwaggerUI：Swagger UI工具的嵌入式版本。它將Swagger JSON解釋為構建豐富的，可定制的Web API功能描述體驗。它包括用於公共方法的內置測試線束。
開始使用：
首先我們要有一個WebAPI項目，假設我們已經創建好了，不懂WebAPI如何創建的請看這篇文章：創建簡單的WebAPI
好了現在我們已經有了項目那我們就開始添加引用吧：
Nuget 命令行 ：Install-Package Swashbuckle.AspNetCore
添加並配置Swagger中間件：
然后配置Startup.cs 文件中的ConfigureServices方法，當然首先不要忘記引用一下using Swashbuckle.AspNetCore.Swagger命名空間，不然info類會報錯。
public void ConfigureServices(IServiceCollection services) { services.AddMvc() .SetCompatibilityVersion(CompatibilityVersion.Version_2_1) .AddJsonOptions(options => options.SerializerSettings.ContractResolver = new Newtonsoft.Json.Serialization.DefaultContractResolver());//JSON首字母小寫解決; services.AddSwaggerGen(options => { options.SwaggerDoc("v1", new Info { Version = "v1", Title = " API 文檔" }); }); }
然后在Configure方法中添加：
//允許中間件為JSON端點服務生成的Siggg app.UseSwagger(); //使中間件能夠服務於輕量級用戶界面（HTML、JS、CSS等），並指定SWAGJER JSON端點 app.UseSwaggerUI(c => { c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1"); // 要在應用程序的根處提供Swagger UI ，請將該RoutePrefix屬性設置為空字符串 c.RoutePrefix = string.Empty; });
啟動效果：
這樣就可以啟動了，配置好以上就是一個最簡單的api文檔示例了。首先你可以訪問：http://localhost:<port>/swagger/v1/swagger.json 這個網址看到端點生成的文檔。
當然你想看到的是這個：http://localhost:<port>/swagger ，你輸入這個網址也可以，當然我把他配置成了根節點，這樣直接啟動根節點就是該頁面。主要是上面代碼中的： c.RoutePrefix = string.Empty這句代碼。
擴展一些顯示：
我們可以擴展一些附加信息，比如作者，許可證，服務條款等。傳遞給該AddSwaggerGen方法的配置：
//Swagger生成器添加到方法中的服務集合中 services.AddSwaggerGen(options => { options.SwaggerDoc("v1", new Info { Version = "v1", Title = " API 文檔", Description = "這是一個示例webapi文檔", //服務條款 TermsOfService = "None", //作者信息 Contact = new Contact { Name = "ybf", Email = string.Empty, Url = "http://www.cnblogs.com/yanbigfeg/" }, //許可證 License = new License { Name = "許可證名字", Url = "http://www.cnblogs.com/yanbigfeg/" } }); });
顯示結果
xml注釋：
啟用XML注釋可為未記錄的公共類型和成員提供調試信息。未記錄的類型和成員由警告消息指示。配置Swagger以使用生成的XML文件。
在我們實現前先設置一下項目屬性：
這樣就可以在項目bin下生成xml文件了。下面進行代碼配置啟用，還是在Startup類中的ConfigureServices方法中，在我們剛才配置的下面在增加以下代碼：
// 設置SWAGER JSON和UI的注釋路徑。 var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"; var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile); options.IncludeXmlComments(xmlPath);
使用反射主要是為了生成一個與項目文件名相同的xml文件。第二部然后是配置文件路徑。這些配置好了以后。我們就可以把方法或者類的三道斜杠（“///”）的注釋添加到動作。我們來看一下效果。
代碼
界面：
注意哦，就是開啟這個功能，項目會自動檢測那些方法或者類沒有注釋，會給出警告。
取消警告小技巧：
當然我們也可以取消掉：我們在個人.csproj文件中使用分號分隔來取消警告信息：
<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'"> <DocumentationFile>bin\Debug\netcoreapp2.1\SwaggerTest.xml</DocumentationFile> <GenerateSerializationAssemblies>On</GenerateSerializationAssemblies> <NoWarn>1701;1702;1705;1591</NoWarn> </PropertyGroup>
這樣就不會有警告提示了。
描述相應類型：
接口使用者最關心的就是接口的返回內容和相應類型啦。下面展示一下201和400一個簡單例子：
我們需要在我們的方法上添加：[ProducesResponseType(201)][ProducesResponseType(400)]
然后添加相應的狀態說明：<response code="201">返回value字符串</response><response code="400">如果id為空</response>
最終代碼應該是這個樣子：
/// <summary> /// values帶id參數的get /// </summary> /// <param name="id">id參數</param> /// <returns>返回字符串類型</returns> /// <response code="201">返回value字符串</response> /// <response code="400">如果id為空</response> // GET api/values/5 [HttpGet("{id}")] [ProducesResponseType(201)] [ProducesResponseType(400)] public ActionResult<string> Get(int id) { return "value"; }
運行起來我們看一下結果：
本例源碼下載：SwaggerTest.rar
傳送門：
WebApi系列文章介紹如何使用WebAPI：