在ASP.Net Core Web API中使用Swagger进行版本控制

使用过程参考:在ASP.Net Core Web API中使用Swagger,本文在此基础上阐述如何进行API文档的版本控制。

1、添加API枚举类型

复制代码
public enum ApiVersion
{
    /// <summary>
    /// v1版本
    /// </summary>
    V1 = 1,
    /// <summary>
    /// v2版本
    /// </summary>
    V2 = 2
}
复制代码

 2、注册Swagger服务

复制代码
public void ConfigureServices(IServiceCollection services)
{
    #region 注册Swagger服务
    services.AddSwaggerGen(options =>
    {
        typeof(ApiVersion).GetEnumNames().ToList().ForEach(version =>
        {
            options.SwaggerDoc(version, new OpenApiInfo()
            {
                Version = version,
                Title = $"webapi {version}",
                Description = $"Asp.NetCore Web API {version}"
            });
        });
    });
    #endregion

    services.AddControllers();
}
复制代码

 3、启用Swagger

复制代码
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
   if
(env.IsDevelopment()) { app.UseDeveloperExceptionPage(); } //启用Swagger中间件 app.UseSwagger(); app.UseSwaggerUI(options => { typeof(ApiVersion).GetEnumNames().ToList().ForEach(version => { options.SwaggerEndpoint($"/swagger/{version}/swagger.json", version); }); }); app.UseRouting();
   app.UseAuthorization(); app.UseEndpoints(endpoints
=> { endpoints.MapControllers(); }); }
复制代码

 4、在控制器中使用ApiExplorerSettings标记

复制代码
namespace WebApi.Controllers.V1
{
    [Route("api/v1/[controller]")]
    [ApiExplorerSettings(GroupName = "V1")]
    [ApiController]
    public class TestController : ControllerBase
    {
        [HttpGet]
        [Route("Get")]
        public string Get()
        {
            return "123456 v1";
        }
    }
}
复制代码
复制代码
namespace WebApi.Controllers.V2
{
    [Route("api/v2/[controller]")]
    [ApiExplorerSettings(GroupName = "V2")]
    [ApiController]
    public class TestController : ControllerBase
    {
        [HttpGet]
        [Route("Get")]
        public string Get()
        {
            return "123456 v2";
        }
    }
}
复制代码

5、注意事项

(1) 在控制器中使用ApiExplorerSettings标记时,GroupName的值要和ApiVersion中的枚举名称一致,否则Swagger列出的API版本列表不会有该控制器的API,导致Swagger网页中该控制器API文档不会出现。

(2) 枚举类型ApiVersion不是必须的,只是用它来获取版本列表,例如可以使用new List<string>() { "V1", "V2" }.ForEach代替typeof(ApiVersion).GetEnumNames().ToList().ForEach。

 6、运行效果

posted @   xhubobo  阅读(600)  评论(0编辑  收藏  举报
编辑推荐:
· 没有源码,如何修改代码逻辑?
· 一个奇形怪状的面试题:Bean中的CHM要不要加volatile?
· [.NET]调用本地 Deepseek 模型
· 一个费力不讨好的项目,让我损失了近一半的绩效!
· .NET Core 托管堆内存泄露/CPU异常的常见思路
阅读排行:
· DeepSeek “源神”启动!「GitHub 热点速览」
· 微软正式发布.NET 10 Preview 1:开启下一代开发框架新篇章
· C# 集成 DeepSeek 模型实现 AI 私有化(本地部署与 API 调用教程)
· DeepSeek R1 简明指南:架构、训练、本地部署及硬件要求
· NetPad:一个.NET开源、跨平台的C#编辑器
点击右上角即可分享
微信分享提示