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