????大家好，我是MapMonkey。今天給大家分享一個(gè)強(qiáng)大的API文檔工具-Swagger。

1、概述

Swagger 是一個(gè)規(guī)范和完整的框架，用于生成、描述、調(diào)用和可視化 RESTful 風(fēng)格的 Web 服務(wù)?？傮w目標(biāo)是使客戶端和文件系統(tǒng)作為服務(wù)器以同樣的速度來更新。文件的方法，參數(shù)和模型緊密集成到服務(wù)器端的代碼，允許API來始終保持同步。其作用主要是 1. 接口的文檔在線自動(dòng)生成；2. 接口功能測(cè)試。
網(wǎng)管地址：https://swagger.io/

官網(wǎng)截圖

• Swagger Codegen: 通過Codegen 可以將描述文件生成html格式和cwiki形式的接口文檔，同時(shí)也能生成多鐘語言的服務(wù)端和客戶端的代碼。支持通過jar包，docker，node等方式在本地化執(zhí)行生成。也可以在后面的Swagger Editor中在線生成。
• Swagger UI:提供了一個(gè)可視化的UI頁面展示描述文件。接口的調(diào)用方、測(cè)試、項(xiàng)目經(jīng)理等都可以在該頁面中對(duì)相關(guān)接口進(jìn)行查閱和做一些簡單的接口請(qǐng)求。該項(xiàng)目支持在線導(dǎo)入描述文件和本地部署UI項(xiàng)目。
• Swagger Editor: 類似于markendown編輯器的編輯Swagger描述文件的編輯器，該編輯支持實(shí)時(shí)預(yù)覽描述文件的更新效果。也提供了在線編輯器和本地部署編輯器兩種方式。
• Swagger Inspector: 感覺和postman差不多，是一個(gè)可以對(duì)接口進(jìn)行測(cè)試的在線版的postman。比在Swagger UI里面做接口請(qǐng)求，會(huì)返回更多的信息，也會(huì)保存你請(qǐng)求的實(shí)際請(qǐng)求參數(shù)等數(shù)據(jù)。
• Swagger Hub：集成了上面所有項(xiàng)目的各個(gè)功能，你可以以項(xiàng)目和版本為單位，將你的描述文件上傳到Swagger Hub中。

2、ASP.NET Core后臺(tái)交互

• 環(huán)境VS2019

image.png

• 創(chuàng)建項(xiàng)目

選擇創(chuàng)建新項(xiàng)目，下一步ASP.NET Core Web應(yīng)用程序，選擇相應(yīng)的文件路徑，選擇Core版本**API項(xiàng)目，開始創(chuàng)建。

image.png

Controllers右擊添加控制器,此處添加一個(gè)默認(rèn)的控制器

image.png

運(yùn)行程序，在瀏覽器輸入[https://localhost:44322/api/default](根據(jù)自己的地址進(jìn)行輸入),如下圖所示：

image.png

3、Swagger工具集成

• 安裝程序包

【項(xiàng)目】—【管理NuGet程序包】—【瀏覽】中搜索“swagger”，安裝前三個(gè)

image.png

• 配置Startup.cs文件

 services.AddSwaggerGen(c =>
  {
   c.SwaggerDoc("v1", new OpenApiInfo { Title = "API 接口", Version = "v1" });
  });

image.png

app.UseSwagger();
app.UseSwaggerUI(c =>
{
 c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});

image.png

• 運(yùn)行程序，在瀏覽器輸入，如下圖所示即表示成功https://localhost:44322/swagger/index.html

image.png

• 啟用XML注釋

右鍵單擊“解決方案資源管理器”中的項(xiàng)目，然后選擇“屬性”
查看“生成”選項(xiàng)卡的“輸出”部分下的“XML 文檔文件”框

image.png

• 配置Startup.cs文件

//Locate the XML file being generated by ASP.NET...
 var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.XML";
 var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);\
 //... and tell Swagger to use those XML comments.
 c.IncludeXmlComments(xmlPath);

image.png

• 代碼中添加注釋

image.png

• 運(yùn)行程序，查看結(jié)果

image.png