在 ASP.NET Core 开发中，组织和管理 API 文档是一个重要的环节。Swagger 是一个常用的工具，用于生成和展示 API 文档。通过使用[ApiExplorerSettings][Tags]特性用于将 API 操作分组到不同的版本。这在多版本 API 开发中非常有用，可以清晰地将不同版本的 API 分开显示。1. 添加特性到控制器GroupName。例如：[ApiExplorerSettings(GroupName = "v1")]摘要：在 ASP.NET Core 开发中，组织和管理 API 文档是一个重要的环节。Swagger 是一个常用的工具，用于生成和展示 API 文档。通过使用
public class ValuesController : ControllerBase
{
[HttpGet]
public IActionResult Get
{
return Ok(new { "value1", "value2" });
}
}2. 配置 Swagger在Startup.cs或Program.cs中配置 Swagger，为每个版本生成一个文档。例如：public void ConfigureServices(IServiceCollection services)
{
services.AddControllers;
// 配置 API 探索器
services.AddApiExplorer;
// 配置 Swagger
services.AddSwaggerGen(options =>
{
options.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
options.SwaggerDoc("v2", new OpenApiInfo { Title = "My API", Version = "v2" });
// 根据 GroupName 匹配文档版本
options.DocInclusionPredicate((docName, apiDesc) =>
{
return apiDesc.GroupName == docName;
});
});
}3. 启用 Swagger UI在Configure方法中启用 Swagger UI，并为每个版本指定一个文档端点。例如：public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
app.UseSwagger;
app.UseSwaggerUI(options =>
{
options.SwaggerEndpoint("/swagger/v1/swagger.json", "My API v1");
options.SwaggerEndpoint("/swagger/v2/swagger.json", "My API v2");
});
app.UseRouting;
app.UseEndpoints(endpoints =>
{
endpoints.MapControllers;
});
}4. 效果
启动应用后，访问 Swagger UI，你会看到两个文档选项：“My API v1” 和 “My API v2”。每个文档中只包含对应版本的 API 操作。
[Tags]特性用于将同一版本的 API 操作分组到不同的功能模块。这有助于在同一个版本中清晰地组织和展示不同的功能模块。1. 添加特性到控制器在控制器或操作方法上添加[Tags]特性，并指定模块名称。例如：[Tags("Users")]public class UsersController : ControllerBase
{
[HttpGet]
public IActionResult GetUsers
{
return Ok(new { "user1", "user2" });
}
}2. 配置 Swagger在Startup.cs或Program.cs中配置 Swagger，无需额外配置，因为[Tags]特性会自动被 Swagger 识别并用于分组。例如：public void ConfigureServices(IServiceCollection services)
{
services.AddControllers;
// 配置 Swagger
services.AddSwaggerGen(options =>
{
options.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
});
}在Configure方法中启用 Swagger UI。例如：public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
app.UseSwagger;
app.UseSwaggerUI(options =>
{
options.SwaggerEndpoint("/swagger/v1/swagger.json", "My API v1");
});
app.UseRouting;
app.UseEndpoints(endpoints =>
{
endpoints.MapControllers;
});
}4. 效果启动应用后，访问 Swagger UI，你会看到一个文档选项：“My API v1”。在该文档中，API 操作会按[Tags]
来源：opendotnet