系列導航及源代碼
- 使用.NET 6開發TodoList應用文章索引
需求
在日常開發中，我們需要給前端提供檔案化的API介面定義，甚至需要模擬架設一個fake服務用來除錯介面欄位，或者對于后端開發人員來說，我們可以通過匯入這個介面定義檔案到Postman或者其他API客戶端，省去我們手動錄入的麻煩，所以本文就實作如何使用Swagger來管理API介面檔案化，
但是在本文中，我們不涉及關于NSwag的相關內容，通過NSwag，我們甚至可以直接生成前端可以使用的介面定義，關于NSwag的使用方法，請參考：NSwag 和 ASP.NET Core 入門以及官方檔案RicoSuter/NSwag，
目標
實作TodoList專案的介面檔案化，
原理與思路
在使用IDE或者cli生成新的Web API專案的時候，專案模版里已經自帶了Swashbuckle.AspNetCore包用來生成swagger檔案，我們需要使用這個包來實作相關功能，
實作
實作基礎的Swagger API檔案
Program中極有可能已經添加了SwaggerGen服務了，我們可以做一點小修改，因為之前我們寫過兩個版本的TodoItemController，希望將兩個版本也反映到swagger檔案中:
// 省略其他...
builder.Services.AddSwaggerGen(s =>
{
s.SwaggerDoc("1.0", new OpenApiInfo { Title = "TodoList API", Version = "1.0"});
s.SwaggerDoc("2.0", new OpenApiInfo { Title = "TodoList API", Version = "2.0"});
});
中間件的引入我們也可以修改一下：
if (app.Environment.IsDevelopment())
{
app.UseSwagger();
app.UseSwaggerUI(s =>
{
s.SwaggerEndpoint("/swagger/1.0/swagger.json", "TodoList API v1.0");
s.SwaggerEndpoint("/swagger/2.0/swagger.json", "TodoList API v2.0");
});
}
如果在API介面版本控制的那一章我們不是使用的通過更改URL的方式實作的API多版本，那么現在只需要對應版本的Controller上添加：
TodoItemController.cs
[Route("/todo-item")]
[ApiExplorerSettings(GroupName = "1.0")]
[ApiController]
public class TodoItemController : ControllerBase
// 省略其他...
以及
TodoItemV2Controller.cs
[Route("/todo-item")]
[ApiExplorerSettings(GroupName = "2.0")]
[ApiController]
public class TodoItemV2Controller : ControllerBase
// 省略其他...
如果是使用URL路徑實作不同版本API的檔案，可以參考這篇文章的實作：ASP.NET Core 3.1 WebApi Swagger與API版本控制的美妙結合
為Swagger添加認證授權功能
為了添加授權支持，我們可以修改Swagger服務選項如下，增加授權配置：
Program.cs
// 省略其他
s.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
{
In = ParameterLocation.Header,
Description = "Add JWT with Bearer",
Name = "Authorization",
Type = SecuritySchemeType.ApiKey,
Scheme = "Bearer"
});
s.AddSecurityRequirement(new OpenApiSecurityRequirement
{
{
new OpenApiSecurityScheme
{
Reference = new OpenApiReference
{
Type = ReferenceType.SecurityScheme,
Id = "Bearer"
},
Name = "Bearer",
},
new List<string>()
}
});
此外因為我們需要驗證Issuer和Audience資訊，所以需要在Token中攜帶這些資訊，這樣Swagger才能授權成功，修改IdentityService發放Token中獲取Claims的邏輯：
IdentityService.cs
private async Task<List<Claim>> GetClaims()
{
// 演示了回傳用戶名和Role兩個claims
var claims = new List<Claim>
{
new(ClaimTypes.Name, User!.UserName),
// 使用fallback去填充這兩個欄位，實際專案里可能不需要這樣做
new(JwtRegisteredClaimNames.Iss, _jwtConfiguration.ValidIssuer ?? "TodoListApi"),
new(JwtRegisteredClaimNames.Aud, _jwtConfiguration.ValidAudience ?? "https://localhost:5050")
};
var roles = await _userManager.GetRolesAsync(User);
claims.AddRange(roles.Select(role => new Claim(ClaimTypes.Role, role)));
return claims;
}
驗證
啟動Api專案，打開swagger地址，可以看到API版本選擇，以及授權控制都在界面上有所顯示，
具體的切換查看我就不貼截圖了，大家可以自己試一試，
一點擴展
匯入API客戶端
右擊swagger界面上的json檔案鏈接選擇另存為，再去對應的API客戶端匯入json檔案即可，
Postman在這方面做的比較好的是它能夠按照json檔案內介面的結構關系生成對應的檔案夾結構，
生成fake服務端
可以去這里：Swagger Editor，上傳swagger json檔案，選擇生成服務端或者客戶端，
為swagger生成完整的資料定義及API注釋檔案
需要開啟XML注釋功能，為此我們同時需要禁止1591warning（為了避免對所有的方法、類、欄位發出沒有xml注釋檔案的警告），修改專案設定如下：
<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
<DocumentationFile>TodoList.Api.xml</DocumentationFile>
<OutputPath></OutputPath>
<NoWarn>1701;1702;1591</NoWarn>
</PropertyGroup>
<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|AnyCPU'">
<NoWarn>1701;1702;1591</NoWarn>
</PropertyGroup>
修改SwaggerGen注入的配置：
TodoList.Api.csproj
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
s.IncludeXmlComments(xmlPath);
我們以CreateTodoList介面為例去添加xml注釋，
TodoListController.cs
/// <summary>
/// 創建新的TodoList，只有Administrator角色的用戶有此權限
/// </summary>
/// <param name="command">創建TodoList命令</param>
/// <returns></returns>
[HttpPost]
[Authorize(Policy = "OnlyAdmin")]
[ServiceFilter(typeof(LogFilterAttribute))]
public async Task<ApiResponse<Domain.Entities.TodoList>> Create([FromBody] CreateTodoListCommand command)
{
return ApiResponse<Domain.Entities.TodoList>.Success(await _mediator.Send(command));
}
再打開swagger檔案查看，可以看到swagger檔案現在已經有介面說明了：
總結
在本文中我們實作了swagger檔案的生成和一些配置選項的作用，如果需要用到更多OpenAPI相關的特性，推薦熟悉一下NSwag這個組件，它提供了更加強大的功能，
下一篇文章我們實作程式的健康檢查功能，
參考資料
- NSwag 和 ASP.NET Core 入門
- RicoSuter/NSwag，
- ASP.NET Core 3.1 WebApi Swagger與API版本控制的美妙結合
轉載請註明出處，本文鏈接：https://www.uj5u.com/net/412747.html
標籤：.NET技术
上一篇：LabVIEW生成.NET的DLL——C#下呼叫NI資料采集設備功能的一種方法 [原創www.cnblogs.com/helesheng]