【WebAPI No.4】Swagger實現API文件功能
介紹：
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; });View Code
啟動效果：
這樣就可以啟動了，配置好以上就是一個最簡單的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/" } }); });View Code
顯示結果
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>View Code
這樣就不會有警告提示了。
描述相應型別：
介面使用者最關心的就是介面的返回內容和相應型別啦。下面展示一下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"; }View Code
執行起來我們看一下結果：
傳送門：
WebApi系列文章介紹如何使用WebAPI：