前言
目前市場上主流的開發模式，幾乎清一色的前后端分離方式，作為服務端開發人員，我們有義務提供給各個客戶端良好的開發文檔，以方便對接，減少溝通時間，提高開發效率；對於開發人員來說，編寫接口文檔需要消耗大量的時間，並且，手動編寫的文檔接口會由於需求的頻繁變動變得難以維護，這就需要一個在接口開發階段可以自動監測接口輸入參數，自動生成文檔的功能；由於 Swagger 插件的出現，這項工作幾乎可以實現完全的自動化。
1. 什么是 Swagger
Swagger 是由 SmartBear 公司開發的一款 API 文檔自動化工具，其采用 Apache 2.0 免費開源授權協議，允許任何人免費使用該工具，利用 Swagger 的特性，可以很方便在沒有任何實現邏輯的情況下生成可視化和與API資源交互界面，Swagger 支持 API 分類導航，提供 API 測試套件，完全的可定制化，對開發人員和 API 消費者都非常友好。
2. 開始使用 Swagger
- 2.1 首先建立一個 Asp.Net Core API 項目，並從 NuGet 上引用 Swagger 包
- 2.2 右鍵點擊項目“依賴項”，選擇 “管理 NuGet 程序包(N)”，這瀏覽標簽頁輸入包名進行安裝，選擇穩定版即可，此處我選擇的版本是 4.0.1
Swashbuckle.AspNetCore
Swashbuckle.AspNetCore.Annotations
- 2.3 首先我們要對項目進行設置，確保生成項目的 XML 文檔，如下圖
右鍵點擊項目-屬性-生成，勾選 "XML 文檔文件"
- 2.4 接下來需要在 Startup.cs 中將 Swagger 加入管道中
static string[] docs = new[] { "未分類" };
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
if (Env.IsDevelopment())
{
services.AddSwaggerGen(options =>
{
foreach (var doc in docs) options.SwaggerDoc(doc, new Info { Version = doc });
options.DocInclusionPredicate((docName, description) =>
{
description.TryGetMethodInfo(out MethodInfo mi);
var attr = mi.DeclaringType.GetCustomAttribute<ApiExplorerSettingsAttribute>();
if (attr != null)
{
return attr.GroupName == docName;
}
else
{
return docName == "未分類";
}
});
options.CustomSchemaIds(d => d.FullName);
options.IncludeXmlComments("Ron.SwaggerTest.xml", true);
});
}
}
// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
app.UseSwagger()
.UseSwaggerUI(options =>
{
options.DocumentTitle = "Ron.liang Swagger 測試文檔";
foreach (var item in docs)
options.SwaggerEndpoint($"/swagger/{item}/swagger.json", item);
});
}
app.UseMvc();
}
}
- 2.5 以上代碼首先定義了一個常量，表示文檔分類列表，默認值給了一個 “未分類”，然后在 ConfigureServices 和 Configure 方法中判斷是開發環境才會引用 Swagger 進行 API 文檔的生成，之所以要增加一個 “未分類”，是因為在我們沒有對 API 進行分組的時候，默認把未分組的 API 歸並到此分類下，好了，現在運行項目
- 2.6 這瀏覽器中輸入地址
http://localhost:5000/swagger/index.html
- 看到 API 文檔已經成功生成
- 可以看到，各種不同的 HttpMethod 都有不同的顏色進行區分顯示，點擊該 API ，可以看到詳細的輸入參數，點擊 API 接口右邊的 Try it out ，還可以對接口進行實時測試，是不是覺得有一中連單元測試都免了的感覺。
- 在上圖中，紅圈部分是我們編寫的 xml 注釋，可以看到，都被完整的抓取並顯示出來了
3. 定義 API 分組
-
上面是默認的 API 文檔，在實際開發中，肯定需要對 API 進行分組和完善輸出參數給消費者，現在就來對 Controller 進行改進，首先是設置分組名稱
-
3.1 定義分組
[Route("api/[controller]"), ApiExplorerSettings(GroupName = "演示分組")]
[ApiController]
public class ValuesController : ControllerBase
- 上面的代碼在 ValuesController 上增加了一個特性 ApiExplorerSettings(GroupName = "演示分組"),這樣就完成了一個分組設置；不過，如果希望該分組能在瀏覽器中顯示，我們還需要在 Startup.cs 中定義的 docs 數組中增加 "演示分組" 名稱
static string[] docs = new[] { "未分類", "演示分組" };
4. 定義 API 接口友好名稱
- 4.1 下面對每個接口進行友好名稱顯示的定義，通過編寫 xml 注釋，並在 summary 節點書寫接口名稱，即可自動顯示到 API 文檔上面
/// <summary>
/// 獲取數組
/// </summary>
/// <remarks>
/// <code>
/// 輸出參數：["value1", "value2"]
/// </code>
/// </remarks>
/// <returns></returns>
[HttpGet]
public ActionResult<IEnumerable<string>> Get()
{
return new string[] { "value1", "value2" };
}
- 4.2 刷新網頁，可以看到，接口友好名稱已經顯示出了了
結語
- Swagger 基礎應用可以幫助我們做到以下內容，現在就開始應用到程序中吧
- 自動生成 API 文檔
- 對每個控制器進行分組
- 自動抓取開發人員編寫的 XML 注釋
- 在 API 文檔界面進行即時測試
- 還有很多過濾等功能，下次有機會再試試
源碼下載
https://github.com/lianggx/EasyAspNetCoreDemo/tree/master/Ron.SwaggerTest