介紹

Swagger 是一個規范和完整的框架，用于生成、描述、調用和可視化 RESTful 風格的 Web 服務。日常可以用于后端開發人員測試接口或者前后端聯調使用。從.net5開始，swagger已經集成到vs2019編譯器中，可以通過勾對選項“啟用OpenAPI支持”顯示基本的swagger配置。

本文示例環境：vs2019、net5

1 基本使用

新建一個NetCore?API項目，為了測試效果，我多創建幾個控制器

image.png

1.1 安裝組件

??<ItemGroup><PackageReference?Include="Swashbuckle.AspNetCore"?Version="5.6.3"?/></ItemGroup>

1.2 注冊swagger服務

在ConfigureServices中

????????public?void?ConfigureServices(IServiceCollection?services){services.AddControllers();services.AddSwaggerGen(c?=>{c.SwaggerDoc("v1",?new?OpenApiInfo?{?Title?=?"WebApi",?Version?=?"v1"?});});}

注意：

//netcore3.0之前版本用法

c.SwaggerDoc("v1", new Info { Title = "WebApi", Version = "v1" });

1.3 使用Swagger

????????public?void?Configure(IApplicationBuilder?app,?IWebHostEnvironment?env){if?(env.IsDevelopment()){app.UseDeveloperExceptionPage();app.UseSwagger();app.UseSwaggerUI(c?=>?c.SwaggerEndpoint("/swagger/v1/swagger.json",?"WebApi?v1"));}app.UseRouting();app.UseAuthorization();app.UseEndpoints(endpoints?=>{endpoints.MapControllers();});}

該示例代碼配置的swagger只在Development環境下顯示，可以根據實際情況來修改

1.4 啟動

運行項目，展示下面的效果

image.png

如果這是你寫的接口，這個時候你的其他同事去看，真的會一臉懵逼，你這寫的都是啥玩意，那么我們來給這加上注釋吧。

????///?<summary>///?用戶控制器///?</summary>[Route("api/[controller]")][ApiController]public?class?UserController?:?ControllerBase{///?<summary>///查詢用戶列表///?</summary>///?<returns></returns>[HttpGet]public?IEnumerable<string>?Get(){return?new?string[]?{?"value1",?"value2"?};}///?<summary>///?查詢用戶詳情///?</summary>///?<param?name="id"></param>///?<returns></returns>[HttpGet("{id}")]public?string?Get(int?id){return?"value";}///?<summary>///?刪除用戶///?</summary>///?<param?name="id"></param>[HttpDelete("{id}")]public?void?Delete(int?id){}}

這樣子加了注釋還不行，swagger還讀取不到我們的注釋，我們還需要生成xml文檔并且讓swagger使用，選中項目右鍵屬性=>生成=>xml文檔文件

image.png

修改注入swagger配置

????????????services.AddSwaggerGen(c?=>{c.SwaggerDoc("v1",?new?OpenApiInfo?{?Title?=?"WebApi",?Version?=?"v1"?});//?使用反射獲取xml文件。并構造出文件的路徑var?xmlFile?=?$"{Assembly.GetExecutingAssembly().GetName().Name}.xml";var?xmlPath?=?Path.Combine(AppContext.BaseDirectory,?xmlFile);//?啟用xml注釋.第二個參數啟用控制器的注釋，默認為false.c.IncludeXmlComments(xmlPath,?true);});

再次啟動項目查看界面

image.png

至此，基礎的配置swagger顯示注釋已經實現了，那么如何調用我們接口那？

image.png

通過該界面，我們可以看到請求地址、請求方式、入參類型、輸出參數等。

注：

通過設置取消顯示警告：1591 ， 可以去除方法和類上面的xml注釋警告

如果實體類不在當前程序集下，需要同樣方式配置實體類程序集的xml文檔到swagger配置

2. swagger傳遞JWT

jwt是一個基于json的、用于在網絡上聲明某種主張的令牌，通常是用三部分組成：頭信息，消息體，簽名。他是一種雙方之間傳遞安全信息的表述性聲明規范。可以做權限驗證的工具，但是目的不是為了數據加密和保護。雖然看似像是加密的數據，但是它并沒有加密，不適合存儲機密信息。

如果我們接口是需要傳遞token才可以訪問，那么我們就需要對我們的swagger配置再進行改造

????????????services.AddSwaggerGen(c?=>{c.SwaggerDoc("v1",?new?OpenApiInfo?{Title?=?"WebApi",?Version?=?"v1"});//?使用反射獲取xml文件。并構造出文件的路徑var?xmlFile?=?$"{Assembly.GetExecutingAssembly().GetName().Name}.xml";var?xmlPath?=?Path.Combine(AppContext.BaseDirectory,?xmlFile);//?啟用xml注釋.第二個參數啟用控制器的注釋，默認為false.c.IncludeXmlComments(xmlPath,?true);var?security?=?new?Dictionary<string,?IEnumerable<string>>?{{"Bearer",?new?string[]?{?}}};c.AddSecurityDefinition("Bearer",?new?OpenApiSecurityScheme(){Description?=?"JWT授權(數據將在請求頭中進行傳輸)?在下方輸入Bearer?{token}?即可，注意兩者之間有空格",Name?=?"Authorization",?//jwt默認的參數名稱In?=?ParameterLocation.Header,?//jwt默認存放Authorization信息的位置(請求頭中)Type?=?SecuritySchemeType.ApiKey,});c.AddSecurityRequirement(new?OpenApiSecurityRequirement{{new?OpenApiSecurityScheme{Reference?=?new?OpenApiReference(){Id?=?"Bearer",Type?=?ReferenceType.SecurityScheme}},Array.Empty<string>()}});});

運行，查看界面，發現界面有所不同

image.png

雖然我手上沒有token，但是我也沒有寫校驗token的代碼，所以我們就暫且看為一個頭部傳遞的工具使用。jwt具體使用后續再講。

token傳遞方式就是在Headers增加 ?Authorization:Bearer {token} ?，然后需要在程序中配置校驗token，當下我們只是模擬swagger在header中傳遞值。

在輸入框輸出：Bearer AABBCC

在Action中獲取我們傳輸的數據

var?token?=?HttpContext.Request.Headers["Authorization"]; image.png

3 參考文檔

https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/web-api-help-pages-using-swagger?view=aspnetcore-5.0

關于swagger的使用操作還有很多，上面有些配置也沒有詳細說到，只說了一些功能性的操作。更詳細操作需要自行學習。

總結

以上是生活随笔為你收集整理的.Net之Swagger基础使用的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。