基于.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工具，提升开发效率和质量。