基於.NET Core 8.0的Swagger文件最佳化分享：根據名稱空間分組顯示

在現代軟體開發中，前後端分離已成為主流趨勢。後端提供API介面，前端透過呼叫這些介面進行數據互動。為了確保前後端開發的順利進行，介面文件顯得尤為重要。Swagger作為一款流行的API文件工具，以其易用性和強大的功能贏得了廣泛的認可。然而，隨著計畫規模的擴大，API介面數量急劇增加，Swagger預設的單頁面展示方式可能會變得難以管理和使用。本文將分享如何在.NET Core 8.0計畫中最佳化Swagger文件，實作根據名稱空間進行分組顯示，提加文檔的可讀性和易用性。

一、Swagger簡介

Swagger是一個規範和完整的框架，用於生成、描述、呼叫和視覺化RESTful風格的Web服務。它透過自動掃描計畫中的控制器和Action，生成對應的API文件，並支持線上測試介面功能。在.NET Core計畫中，Swashbuckle是Swagger的官方實作，它提供了對Swagger的無縫整合支持。

二、為什麽需要最佳化Swagger文件

在大型計畫中，隨著API介面數量的不斷增加，Swagger預設將所有介面展示在一個頁面上的方式顯得越來越笨重。這不僅使得前端開發人員難以快速定位到所需介面，還增加了文件的載入時間和渲染難度。因此，對Swagger文件進行最佳化，實作介面的分組顯示，變得尤為重要。

三、根據名稱空間分組顯示的實作

1. 安裝Swashbuckle.AspNetCore

首先，你需要在.NET Core 8.0計畫中安裝Swashbuckle.AspNetCore NuGet包。可以透過NuGet包管理器搜尋並安裝，或者在計畫目錄下執行以下命令：

dotnet add package Swashbuckle.AspNetCore


2. 配置Swagger服務

在 Startup.cs 檔的 ConfigureServices 方法中，你需要配置Swagger服務。這裏我們將使用名稱空間作為分組依據，因此需要自訂一些配置。

publicvoidConfigureServices(IServiceCollection services)
{
services.AddControllers();
// 添加Swagger生成器
services.AddSwaggerGen(c =>
{
// 定義多個Swagger文件
var namespaces = Assembly.GetExecutingAssembly().GetTypes()
.Where(t => typeof(ControllerBase).IsAssignableFrom(t) && !t.IsAbstract)
.Select(t => t.Namespace).Distinct();
foreach (var ns in namespaces)
{
var groupName = ns.Replace('.', '_'); // 將名稱空間點替換為底線，以符合URL命名規範
c.SwaggerDoc(groupName, new OpenApiInfo
{
Title = $"{ns} API",
Version = "v1",
Description = $"API文件 - {ns}"
});
}
// 設定要展示的介面
c.DocInclusionPredicate((docName, apiDesc) =>
{
if (!apiDesc.TryGetMethodInfo(out MethodInfo methodInfo))
returnfalse;
var controllerNamespace = methodInfo.DeclaringType?.Namespace;
if (string.IsNullOrEmpty(controllerNamespace))
returnfalse;
var controllerGroupName = controllerNamespace.Replace('.', '_');
return controllerGroupName == docName;
});
// 設定xml文件註釋路徑
var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);
var xmlPath = Path.Combine(basePath, "YourProjectName.xml");
c.IncludeXmlComments(xmlPath, true);
// 添加授權資訊（如果有需要）
c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
{
Description = "請輸入帶有Bearer開頭的Token",
Name = "Authorization",
In = ParameterLocation.Header,
Type = SecuritySchemeType.ApiKey
});
c.AddSecurityRequirement(new OpenApiSecurityRequirement
{
{
new OpenApiSecurityScheme
{
Reference = new OpenApiReference
{
Type = ReferenceType.SecurityScheme,
Id = "Bearer"
}
},
Array.Empty<string>()
}
});
});
}








註意：

3. 配置Swagger UI

接下來，在 Startup.cs 檔的 Configure 方法中，配置Swagger UI以顯示分組後的文件。

publicvoidConfigure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
app.UseRouting();
// 啟用Swagger文件服務
app.UseSwagger();
// 啟用Swagger UI樣式
app.UseSwaggerUI(c =>
{
// 載入所有分組文件
var namespaces = Assembly.GetExecutingAssembly().GetTypes()
.Where(t => typeof(ControllerBase).IsAssignableFrom(t) && !t.IsAbstract)
.Select(t => t.Namespace).Distinct();
foreach (var ns in namespaces)
{
var groupName = ns.Replace('.', '_');
c.SwaggerEndpoint($"/swagger/{groupName}/swagger.json", $"{ns} API");
}
c.DocExpansion(DocExpansion.None); // 不自動展開文件
});
app.UseAuthorization();
app.UseEndpoints(endpoints =>
{
endpoints.MapControllers();
});
}







4. 控制器和Action的名稱空間

為了使上述分組策略生效，你需要確保控制器類位於具有明確名稱空間的類中。例如：

namespaceYourProject.Controllers.Users
{
[ApiController]
[Route("[controller]")]
public classUserController : ControllerBase
{
// ...
}
}
namespaceYourProject.Controllers.Orders
{
[ApiController]
[Route("[controller]")]
public classOrderController : ControllerBase
{
// ...
}
}

5. 測試和最佳化

完成上述配置後，啟動你的.NET Core計畫，並存取Swagger UI（通常是 http://localhost:<埠>/swagger ）。你應該能看到根據名稱空間分組的API文件列表。

四、進一步最佳化

雖然基於名稱空間的分組策略已經能夠顯著提高Swagger文件的可讀性和易用性，但在實際套用中，可能還需要進行進一步的最佳化。以下是一些建議：

1. 效能最佳化

隨著API介面數量的增加，Swagger文件的載入和渲染時間可能會變長。可以透過以下方式進行最佳化：

2. 自訂UI

Swagger UI支持自訂樣式和布局。你可以透過修改Swagger UI的CSS和JavaScript檔，或者透過Swagger UI提供的外掛程式系統，實作個人化的UI設計。

3. 整合認證

如果你的API介面需要認證，可以在Swagger配置中添加認證資訊，並在Swagger UI中整合認證流程，使得前端開發人員能夠更方便地進行介面測試。

4. 國際化支持

Swagger UI支持多語言。你可以透過配置Swagger文件中的後設資料，以及修改Swagger UI的資原始檔，實作介面文件的國際化支持。

五、總結

在.NET Core 8.0計畫中，透過合理配置Swashbuckle.AspNetCore，我們可以輕松實作Swagger文件的分組顯示，提加文檔的可讀性和易用性。本文介紹了基於名稱空間的分組策略，並提供了詳細的配置步驟和C#程式碼範例。同時，還探討了進一步最佳化Swagger文件的方法和思路。希望這些內容能夠幫助你在實際計畫中更好地使用Swagger工具，提升開發效率和品質。