基於 abp vNext 和 .NET Core 開發部落格專案 - 再說Swagger，分組、描述、小綠鎖
阿新 • • 發佈：2020-05-22
在開始本篇正文之前，解決一個 @瘋瘋過 指出的錯誤，再次感謝指正。
步驟如下：
* 刪掉`.Domain.Shared`層中的專案引用，新增nuget依賴包`Volo.Abp.Identity.Domain.Shared`，可以使用命令：`Install-Package Volo.Abp.Identity.Domain.Shared`
* 在`.Domain`層中引用專案`.Domain.Shared`，在模組類中新增依賴`typeof(MeowvBlogDomainSharedModule)`
* 將`.EntityFrameworkCore`層中的引用專案`.Domain.Shared`改成`.Domain`。
---
上一篇文章(https://www.cnblogs.com/meowv/p/12924409.html)完成了對API返回模型的封裝，緊接著我打算繼續來折騰一下Swagger，之前的文章中已經簡單用起了Swagger，本篇還是圍繞它讓其發揮更高的更多的價值。
當我們的專案不斷壯大，API持續增多，這時如果想要快速準確定位到某個API可能不是那麼容易，需要翻半天才能找對我們的API。於是對Swagger API文件分組和詳細的文件描述就有必要了，就本專案而言，部落格系統可以分組為：部落格前臺介面、部落格後臺介面、其它公共介面、JWT認證授權介面。
其中，部落格後臺組中的介面需要授權後才可以呼叫，需要授權那麼就涉及到身份驗證，在這裡準備採用JWT(JSON WEB TOKEN)的方式進行。
## 分組
對Swagger進行分組很簡單，在`.Swagger`層中的擴充套件方法`AddSwagger(this IServiceCollection services)`中多次呼叫`options.SwaggerDoc(...)`即可，像這樣
```CSharp
...
options.SwaggerDoc("v1", new OpenApiInfo
{
Version = "1.0.0",
Title = "我的介面啊1",
Description = "介面描述1"
});
options.SwaggerDoc("v2", new OpenApiInfo
{
Version = "1.0.0",
Title = "我的介面啊2",
Description = "介面描述2"
});
...
...
```
不過這樣顯得有點low，然後可以轉變一下思路使用遍歷的方式進行。`options.SwaggerDoc(...)`接收兩個引數：`string name, OpenApiInfo info`。
`name`：可以理解為當前分組的字首；`OpenApiInfo`：有許多可配置的引數，在這裡我只用到三個，`Version`、`Title`、`Description`。
要注意，當在`AddSwagger(...)`中呼叫完後，還需要在我們的擴充套件方法`UseSwaggerUI(this IApplicationBuilder app)`中`options.SwaggerEndpoint()`使用它，同樣的也用遍歷的方法。它接收的的引數：`string url, string name`。
`url`：這裡的`url`要與前面配置的`name`引數對應。
`name`：我們自定義顯示的分組名稱。
於是可以直接在擴充套件方法中新建一個內部類：`SwaggerApiInfo`
```CSharp
internal class SwaggerApiInfo
{
///
/// URL字首
///
public string UrlPrefix { get; set; }
///
/// 名稱
///
public string Name { get; set; }
///
///
public OpenApiInfo OpenApiInfo { get; set; }
}
```
然後新建一個`List`手動為其初始化一些值。
```CSharp
...
///
/// Swagger分組資訊，將進行遍歷使用
/// ApiInfos = new List()
{
new SwaggerApiInfo
{
UrlPrefix = Grouping.GroupName_v1,
Name = "部落格前臺介面",
OpenApiInfo = new OpenApiInfo
{
Version = version,
Title = "阿星Plus - 部落格前臺介面",
Description = description
}
},
new SwaggerApiInfo
{
UrlPrefix = Grouping.GroupName_v2,
Name = "部落格後臺介面",
OpenApiInfo = new OpenApiInfo
{
Version = version,
Title = "阿星Plus - 部落格後臺介面",
Description = description
}
},
new SwaggerApiInfo
{
UrlPrefix = Grouping.GroupName_v3,
Name = "通用公共介面",
OpenApiInfo = new OpenApiInfo
{
Version = version,
Title = "阿星Plus - 通用公共介面",
Description = description
}
},
new SwaggerApiInfo
{
UrlPrefix = Grouping.GroupName_v4,
Name = "JWT授權介面",
OpenApiInfo = new OpenApiInfo
{
Version = version,
Title = "阿星Plus - JWT授權介面",
Description = description
}
}
};
...
```
`version`：我們將其配置在`appsettings.json`中，做到動態可以修改。
```CSharp
//AppSettings.cs
...
///
/// ApiVersion
///
/// 分組
///
/// 部落格前臺介面組
///
public const string GroupName_v1 = "v1";
///
/// 部落格後臺介面組
///
public const string GroupName_v2 = "v2";
///
/// 其他通用介面組
///
public const string GroupName_v3 = "v3";
///
/// JWT授權介面組
///
public const string GroupName_v4 = "v4";
}
...
```
現在修改擴充套件方法`AddSwagger(...)`，遍歷`List`。
```CSharp
...
public static IServiceCollection AddSwagger(this IServiceCollection services)
{
return services.AddSwaggerGen(options =>
{
//options.SwaggerDoc("v1", new OpenApiInfo
//{
// Version = "1.0.0",
// Title = "我的介面啊",
// Description = "介面描述"
//});
// 遍歷並應用Swagger分組資訊
ApiInfos.ForEach(x =>
{
options.SwaggerDoc(x.UrlPrefix, x.OpenApiInfo);
});
...
});
}
...
```
在擴充套件方法`UseSwaggerUI(...)`使用，通用也需要遍歷。
```CSharp
...
// 遍歷分組資訊，生成Json
ApiInfos.ForEach(x =>
{
options.SwaggerEndpoint($"/swagger/{x.UrlPrefix}/swagger.json", x.Name);
});
...
```
細心的同學可以發現，我們前幾篇文章開啟Swagger文件的時候都是需要手動更改URL地址：`.../swagger`才能正確進入，其實Swagger是支援配置路由的。同時咱們也將頁面Title也給改了吧。看下面`UseSwaggerUI(...)`完整程式碼：
```CSharp
...
///
/// UseSwaggerUI
///
///
public static void UseSwaggerUI(this IApplicationBuilder app)
{
app.UseSwaggerUI(options =>
{
// 遍歷分組資訊，生成Json
ApiInfos.ForEach(x =>
{
options.SwaggerEndpoint($"/swagger/{x.UrlPrefix}/swagger.json", x.Name);
});
// 模型的預設擴充套件深度，設定為 -1 完全隱藏模型
options.DefaultModelsExpandDepth(-1);
// API文件僅展開標記
options.DocExpansion(DocExpansion.List);
// API字首設定為空
options.RoutePrefix = string.Empty;
// API頁面Title
options.DocumentTitle = "