基于 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”;

/// <summary>/// 博客后臺接口組/// </summary>public const string GroupName_v2 = "v2";/// <summary>/// 其他通用接口組/// </summary>public const string GroupName_v3 = "v3";/// <summary>/// JWT授權接口組/// </summary>public const string GroupName_v4 = "v4";}

…
現在修改擴展方法AddSwagger(…)，遍歷List。

…
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(…)使用，通用也需要遍歷。

…
// 遍歷分組信息，生成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);
});

// 模型的默認擴展深度，設置為 -1 完全隱藏模型options.DefaultModelsExpandDepth(-1);// API文檔僅展開標記options.DocExpansion(DocExpansion.List);// API前綴設置為空options.RoutePrefix = string.Empty;// API頁面Titleoptions.DocumentTitle = "😍接口文檔 - 阿星Plus???";});}

…
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 = “這里是一些通用的公共接口” }
}
};

// 按照Name升序排序swaggerDoc.Tags = tags.OrderBy(x => x.Name).ToList();} }

}
實現Apply(…)方法后，使用Linq語法對文檔排個序，然后最重要的使用這個Filter，在擴展方法AddSwagger(…)中使用

public static IServiceCollection AddSwagger(this IServiceCollection services){return services.AddSwaggerGen(options =>{...// 應用Controller的API文檔描述信息options.DocumentFilter<SwaggerDocumentFilter>();});}

再打開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，分组、描述、小绿锁的全部內容，希望文章能夠幫你解決所遇到的問題。

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