在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、運行效果