Asp.Net Core遇到Swagger(一)-Swashbuckle基礎(chǔ)篇
1
前言
作為一名后端，接口開發(fā)好了，與前端對接或者三方公司進行對接時，每次反反復(fù)復(fù)的依靠人力構(gòu)建接口說明文檔，每一次接口變更，輸入輸出結(jié)果字段變化，不勝其煩，能依據(jù)接口動態(tài)生成api對接文檔豈不是更好，有變更，重新生成一下項目就好，還能在線調(diào)試接口，后端可控粒度高，你一定腦子里閃過Swagger，廢話不多說，沖~
2
概述
Swagger作為一個Api文檔生成和展示工具，能夠依據(jù)一套OpenApi數(shù)據(jù)規(guī)范，自動的從系統(tǒng)中提取的注釋信息，生成動態(tài)的生成Api說明文檔，OpenApi規(guī)范本身是脫胎于Swagger；
Asp.Net Core中與之對應(yīng)的類庫分別為Swashbuckle，NSwag，參考鏈接：https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-5.0&tabs=visual-studio
Swashbuckle 有三個主要組成部分：
Swashbuckle.AspNetCore.Swagger：將
SwaggerDocument對象公開為 JSON 終結(jié)點的 Swagger 對象模型和中間件。Swashbuckle.AspNetCore.SwaggerGen：從路由、控制器和模型直接生成
SwaggerDocument對象的 Swagger 生成器。它通常與 Swagger 終結(jié)點中間件結(jié)合，以自動公開 Swagger JSON。Swashbuckle.AspNetCore.SwaggerUI：Swagger UI 工具的嵌入式版本。它解釋 Swagger JSON 以構(gòu)建描述 Web API 功能的可自定義的豐富體驗。它包括針對公共方法的內(nèi)置測試工具
NSwag
NSwag 提供了下列功能：
能夠使用 Swagger UI 和 Swagger 生成器。
靈活的代碼生成功能
借助
NSwag，無需使用現(xiàn)有API。也就是說，可使用包含Swagger的第三方API，并生成客戶端實現(xiàn)。使用NSwag，可以加快開發(fā)周期，并輕松適應(yīng)API更改
3
基礎(chǔ)應(yīng)用
本章主要講解Swashbuckle的基本使用技巧
3.1 開發(fā)環(huán)境
Windows10
Vs2019
Asp.Net Core 3.1 Web API
3.2 創(chuàng)建項目
選擇項目模板為ASP.Net Core Web API項目名稱為swaggertestbase，項目依賴的框架版本為.Net Core 3.1
3.3 引用類庫包
Nuget包管理頁面中的瀏覽頁簽，輸入swagger進行搜索，找到截圖中的對應(yīng)類庫Swashbuckle.AspNetCore.SwaggerGen和Swashbuckle.AspNetCore.SwaggerUI，選擇6.0.0，選擇安裝按鈕即可，剩余無腦確定
安裝成功后，引用中目錄如下：
3.4 基礎(chǔ)配置
引入命名空間
在Startup.cs中引入Swashbuckle.AspNetCore.SwaggerGen
using Swashbuckle.AspNetCore.SwaggerGen;
注冊服務(wù)
在Startup.cs的ConfigureServices服務(wù)中注冊服務(wù)
......
public void ConfigureServices(IServiceCollection services)
{
//注冊服務(wù)
services.AddSwaggerGen();
services.AddControllers();
}
......
啟用靜態(tài)文件中間件
由于swagger-ui需要允許客戶端訪問服務(wù)端靜態(tài)的樣式和資源，所以需要服務(wù)配置函數(shù)Configure中路由中間件之前，啟用靜態(tài)中間件UseStaticFiles
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
.....
//啟動靜態(tài)文件中間
app.UseStaticFiles();
.....
//啟動路由中間件
app.UseRouting();
.....
}
配置Swagger中間件以及SwaggerUI中間件
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
.....
//啟動靜態(tài)文件中間
app.UseStaticFiles();
#region Swagger中間件相關(guān)
//添加swagger配置，并啟動中間件
app.UseSwagger();
//啟用Swagger-ui中間件，并配置swagger json的請求終節(jié)點
app.UseSwaggerUI();
#endregion
//啟動路由中間件
app.UseRouting();
.....
}
啟動項目
訪問地址http://localhost:5000/swagger/v1/swagger.json，返回如下結(jié)果，表示默認對應(yīng)Swagger Api Json結(jié)果如下：
{
"openapi": "3.0.1",
"info": {
"title": "swaggertestbase",
"version": "1.0"
},
"servers": [
{
"url": "http://localhost:5000"
}
],
"paths": {
"/WeatherForecast": {
"get": {
"tags": [
"WeatherForecast"
]
}
}
}
}
訪問地址http://localhost:5000/swagger/index.html，訪問結(jié)果如下：
以上為默認情況下，Swashbuckle基礎(chǔ)的相關(guān)內(nèi)容。
往期推薦
