【ASP.NET Core Swagger】2、多文档(Group)
生成器将在单个 Swagger 文档中包含所有 API 操作。但是,如有必要,您可以创建多个文档。例如,您可能希望每个 API 版本都有一个单独的文档。
案例
添加服务、中间件(v1、v2)
builder.Services.AddSwaggerGen(options =>
{
//定义多个Swagger 文档
options.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo()
{
Title = "v1 标题",
Version = "v1"
});
options.SwaggerDoc("v2", new Microsoft.OpenApi.Models.OpenApiInfo()
{
Title = "v2 标题",
Version = "v2"
});
});
app.UseSwagger();
app.UseSwaggerUI(options => {
options.SwaggerEndpoint("/swagger/v1/swagger.json", "v1~~~");
options.SwaggerEndpoint("/swagger/v2/swagger.json", "v2~~~");
});
添加两个Controller,分别属于v1、v2:
namespace SwaggerVersion.Controllers.v1
{
[ApiController]
[Route("[controller]")]
[ApiExplorerSettings(GroupName = "v1")]
public class OrderController : ControllerBase
{
[HttpGet]
public IEnumerable<string> Get()
{
return new string[] { "value1", "value2" };
}
}
}
namespace SwaggerVersion.Controllers.v2
{
[ApiController]
[Route("[controller]")]
[ApiExplorerSettings(GroupName = "v2")]
public class OrderController : ControllerBase
{
[HttpGet]
public IEnumerable<string> Get()
{
return new string[] { "value1", "value2" };
}
}
}
按约定为文档分配操作
您可以连接以下约定以根据控制器命名空间进行分组,就不需要[ApiExplorerSettings]
了
// ApiExplorerGroupPerVersionConvention.cs
public class ApiExplorerGroupPerVersionConvention : IControllerModelConvention
{
public void Apply(ControllerModel controller)
{
var controllerNamespace = controller.ControllerType.Namespace; // e.g. "Controllers.V1"
var apiVersion = controllerNamespace.Split('.').Last().ToLower();
controller.ApiExplorer.GroupName = apiVersion;
}
}
// Startup.cs
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc(c =>
c.Conventions.Add(new ApiExplorerGroupPerVersionConvention())
);
...
}
【推荐】国内首个AI IDE,深度理解中文开发场景,立即下载体验Trae
【推荐】编程新体验,更懂你的AI,立即体验豆包MarsCode编程助手
【推荐】抖音旗下AI助手豆包,你的智能百科全书,全免费不限次数
【推荐】轻量又高性能的 SSH 工具 IShell:AI 加持,快人一步
· 分享4款.NET开源、免费、实用的商城系统
· 全程不用写代码,我用AI程序员写了一个飞机大战
· MongoDB 8.0这个新功能碉堡了,比商业数据库还牛
· 白话解读 Dapr 1.15:你的「微服务管家」又秀新绝活了
· 上周热点回顾(2.24-3.2)