基于 abp vNext 和 .NET Core 开发博客项目 - 再说Swagger，分组、描述、小绿锁
基于 abp vNext 和 .NET Core 開發博客項目 - 再說Swagger，分組、描述、小綠鎖
https://github.com/Meowv/Blog
在開始本篇正文之前，解決一個 @瘋瘋過 指出的錯誤，再次感謝指正。
圖片
步驟如下：
刪掉.Domain.Shared層中的項目引用，添加nuget依賴包Volo.Abp.Identity.Domain.Shared，可以使用命令：Install-Package Volo.Abp.Identity.Domain.Shared
在.Domain層中引用項目.Domain.Shared，在模塊類中添加依賴typeof(MeowvBlogDomainSharedModule)
將.EntityFrameworkCore層中的引用項目.Domain.Shared改成.Domain。
圖片
上一篇文章完成了對API返回模型的封裝，緊接著我打算繼續來折騰一下Swagger，之前的文章中已經簡單用起了Swagger，本篇還是圍繞它讓其發揮更高的更多的價值。
當我們的項目不斷壯大，API持續增多，這時如果想要快速準確定位到某個API可能不是那么容易，需要翻半天才能找對我們的API。于是對Swagger API文檔分組和詳細的文檔描述就有必要了，就本項目而言，博客系統可以分組為：博客前臺接口、博客后臺接口、其它公共接口、JWT認證授權接口。
其中，博客后臺組中的接口需要授權后才可以調用，需要授權那么就涉及到身份驗證，在這里準備采用JWT(JSON WEB TOKEN)的方式進行。
分組
對Swagger進行分組很簡單，在.Swagger層中的擴展方法AddSwagger(this IServiceCollection services)中多次調用options.SwaggerDoc(…)即可，像這樣
…
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
internal class SwaggerApiInfo{/// <summary>/// URL前綴/// </summary>public string UrlPrefix { get; set; }/// <summary>/// 名稱/// </summary>public string Name { get; set; }/// <summary>/// <see cref="Microsoft.OpenApi.Models.OpenApiInfo"/>/// </summary>public OpenApiInfo OpenApiInfo { get; set; }}然后新建一個List手動為其初始化一些值。
…
///
/// Swagger分組信息，將進行遍歷使用
///
private static readonly List 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中，做到動態可以修改。
//AppSettings.cs
…
///
/// ApiVersion
///
public static string ApiVersion => _config[“ApiVersion”];
…
//appsettings.json
{
…
“ApiVersion”: “1.0.0”
…
}
description：因為多次使用，就定義一個變量，內容自擬主要是一些介紹性的描述，將在Swagger界面進行顯示。
UrlPrefix：分別為，v1,v2,v3,v4。在Domain.Shared層中為其定義好常量
//MeowvBlogConsts.cs
…
///
/// 分組
///
public static class Grouping
{
///
/// 博客前臺接口組
///
public const string GroupName_v1 = “v1”;
…
現在修改擴展方法AddSwagger(…)，遍歷List。
…
public static IServiceCollection AddSwagger(this IServiceCollection services)
{
return services.AddSwaggerGen(options =>
{
//options.SwaggerDoc(“v1”, new OpenApiInfo
//{
// Version = “1.0.0”,
// Title = “我的接口啊”,
// Description = “接口描述”
//});
…
在擴展方法UseSwaggerUI(…)使用，通用也需要遍歷。
…
// 遍歷分組信息，生成Json
ApiInfos.ForEach(x =>
{
options.SwaggerEndpoint($"/swagger/{x.UrlPrefix}/swagger.json", x.Name);
});
…
細心的同學可以發現，我們前幾篇文章打開Swagger文檔的時候都是需要手動更改URL地址：…/swagger才能正確進入，其實Swagger是支持配置路由的。同時咱們也將頁面Title也給改了吧。看下面UseSwaggerUI(…)完整代碼：
…
///
/// UseSwaggerUI
///
///
public static void UseSwaggerUI(this IApplicationBuilder app)
{
app.UseSwaggerUI(options =>
{
// 遍歷分組信息，生成Json
ApiInfos.ForEach(x =>
{
options.SwaggerEndpoint($"/swagger/{x.UrlPrefix}/swagger.json", x.Name);
});
…
options.DefaultModelsExpandDepth(-1);是模型的默認擴展深度，設置為 -1 完全隱藏模型。
options.DocExpansion(DocExpansion.List);代表API文檔僅展開標記，不默然展開所有接口，需要我們手動去點擊才展開，可以自行查看DocExpansion。
options.RoutePrefix = string.Empty;代表路由設置為空，直接打開頁面就可以訪問了。
options.DocumentTitle = “😍接口文檔 - 阿星Plus???”;是設置文檔頁面的標題的。
完成以上操作，在Controller中使用 Attribute：[ApiExplorerSettings(GroupName = …)]指定是哪個分組然后就可以愉快的使用了。
默認不指定的話就是全部都有，目前只有兩個Controller，我們將HelloWorldController設置成v3，BlogController設置成v1。
//HelloWorldController.cs
…
[ApiExplorerSettings(GroupName = Grouping.GroupName_v3)]
public class HelloWorldController : AbpController
{
…
}
…
//BlogController.cs
…
[ApiExplorerSettings(GroupName = Grouping.GroupName_v1)]
public class BlogController : AbpController
{
…
}
…
編譯運行，打開我們的Swagger文檔看一下。
圖片
圖片
自己試著換切換一下分組試試吧，大功告成。
描述
在Swagger文檔中，默認只顯示我們的Controller的名稱，其實他也是支持描述信息的，這是就需要我們自行擴展了。在.Swagger層新建一個文件夾Filters，添加SwaggerDocumentFilter類來實現IDocumentFilter接口。
//SwaggerDocumentFilter.cs
using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;
using System.Collections.Generic;
using System.Linq;
namespace Meowv.Blog.Swagger.Filters
{
///
/// 對應Controller的API文檔描述信息
///
public class SwaggerDocumentFilter : IDocumentFilter
{
public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
{
var tags = new List
{
new OpenApiTag {
Name = “Blog”,
Description = “個人博客相關接口”,
ExternalDocs = new OpenApiExternalDocs { Description = “包含：文章/標簽/分類/友鏈” }
}
new OpenApiTag {
Name = “HelloWorld”,
Description = “通用公共接口”,
ExternalDocs = new OpenApiExternalDocs { Description = “這里是一些通用的公共接口” }
}
};
}
實現Apply(…)方法后，使用Linq語法對文檔排個序，然后最重要的使用這個Filter，在擴展方法AddSwagger(…)中使用
再打開Swagger文檔看看效果。
圖片
ok，此時描述信息也出來了。
小綠鎖
在Swagger文檔中開啟小綠鎖是非常簡單的，只需添加一個包：Swashbuckle.AspNetCore.Filters，直接使用命令安裝：Install-Package Swashbuckle.AspNetCore.Filters
然后再擴展方法AddSwagger(this IServiceCollection services)中調用
public static IServiceCollection AddSwagger(this IServiceCollection services)
{
return services.AddSwaggerGen(options =>
{
…
var security = new OpenApiSecurityScheme
{
Description = “JWT模式授權，請輸入 Bearer {Token} 進行身份驗證”,
Name = “Authorization”,
In = ParameterLocation.Header,
Type = SecuritySchemeType.ApiKey
};
options.AddSecurityDefinition(“JWT”, security);
options.AddSecurityRequirement(new OpenApiSecurityRequirement { { security, new List() } });
options.OperationFilter();
options.OperationFilter();
options.OperationFilter();
…
});
}
以上便實現了在Swagger文檔中顯示小綠鎖，我們new的OpenApiSecurityScheme對象，具體參數大家可以自行看一下注釋就明白具體含義。分別調用options.AddSecurityDefinition(…)、options.AddSecurityRequiremen(…)、options.OperationFilter(…)，編譯運行，打開瞅瞅。
圖片
現在只是做了小綠鎖的顯示，但是并沒有實際意義，因為在.net core中還需要配置我們的身份認證授權代碼，才能具體發揮其真正的作用，所以目前我們的api還是處于裸奔狀態，誰都能調用你的api，等你發現你寫的文章都被別人刪了，你都不知道為什么。
實現JWT，將在下篇文章中詳細說明，本篇到這里就結束了，我們完善了Swagger文檔，給接口加了分組、描述，還有小綠鎖。老鐵，你學會了嗎？😁😁😁
開源地址：https://github.com/Meowv/Blog/tree/blog_tutorial
總結
以上是生活随笔為你收集整理的基于 abp vNext 和 .NET Core 开发博客项目 - 再说Swagger，分组、描述、小绿锁的全部內容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： 基于 abp vNext 和 .NET
- 下一篇： 基于 abp vNext 和 .NET