利用swagger和API Version實現api版本控制

場景：

　　在利用.net core進行api接口開發時，經常會因為需求，要開發實現統一功能的多版本的接口。比如版本V1是給之前用戶使用，然后新用戶有新需求，這時候可以單獨給這個用戶寫接口，也可以在V1基礎上寫版本V2，這樣V1的用戶要使用V2的接口，只有稍微改一下就可以了。

實現：

　　1.APIVersion

　　首先需要安裝Nuget包：Microsoft.AspNetCore.Mvc.Versioning  以及  Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer

　　然后在ConfigureServices中添加以下內容;

            // API接口版本
            services.AddApiVersioning(o => {
                o.ReportApiVersions = true;
                o.AssumeDefaultVersionWhenUnspecified = true;
                //o.ApiVersionReader = new HeaderApiVersionReader("version");
                o.DefaultApiVersion = new ApiVersion(1, 0);
            });
            services.AddVersionedApiExplorer( o => {
                o.GroupNameFormat = "'v'VVV";
                o.SubstituteApiVersionInUrl = true;
            });        

　　同時在Configure中添加以下內容：

app.UseApiVersioning();

　　ApiVersion用來配置默認版本，版本位置等，這里的ApiVersionReader可以設定api版本位置，比如是http中的Header位置，還是放在請求中。

　　VersionedApiExplorer用來版本管理，其中的GroupNameFormat是api組名格式，而SubstituteApiVersionInUrl 是設置在url中替換版本

　　之后在控制器上添加版本，如下：

    /// <summary>
    /// 角色相關
    /// </summary>
    [ApiVersion("2.0")]
    [TypeFilter(typeof(AuthFilter))]
    [ApiController]
    [Route("api/v{version:apiVersion}/[controller]/[action]")]
    public class RoleController:ControllerBase
    {
        /// <summary>
        /// 添加角色,版本2
        /// </summary>
        /// <param name="req"></param>
        /// <returns></returns>
        [HttpPost,MapToApiVersion("2.0")]
        public Response<DTO_Id> AddRole(DTO_AddOrUpdate_Role_V2 req)
        {
        }
    }

 　　/// <summary>
    /// 角色相關，版本1
    /// </summary>
    [ApiVersion("1.0")]
    [TypeFilter(typeof(AuthFilter))]
    [ApiController]
    [Route("api/v{version:apiVersion}/[controller]/[action]")]
    public class RoleController:ControllerBase
    {
        /// <summary>
        /// 添加角色
        /// </summary>
        /// <param name="req"></param>
        /// <returns></returns>
        [HttpPost]
        public Response<DTO_Id> AddRole(DTO_AddOrUpdate_Role req) 
        {
            
        }
    }

　　這里在apiVersion中設置控制器版本，同時可以通過參數不同來重載函數。這樣就實現了版本控制

　　2.swagger

　　首先先導入nuget包，Swashbuckle.AspNetCore

　　在ConfigureService中配置swaager，如下;

 　　　　　　var provider = services.BuildServiceProvider().GetRequiredService<IApiVersionDescriptionProvider>();
            // swagger
            services.AddSwaggerGen(c => 
            {
              
                // 排序方式
                c.OrderActionsBy(o => o.HttpMethod);
                foreach (var item in provider.ApiVersionDescriptions) 
                {
                    c.SwaggerDoc(item.GroupName, new OpenApiInfo 
                    {
                        Title = "WebAPI" + item.GroupName,
                        Version = item.ApiVersion.MajorVersion.ToString() + "." + item.ApiVersion.MinorVersion
                    });

                }
                c.OperationFilter<GlobalHttpHeaderOperationFilter>();
                // 重載方式
                c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());

                foreach (var name in Directory.GetFiles(AppContext.BaseDirectory, "*.*",
                    SearchOption.AllDirectories).Where(f => Path.GetExtension(f).ToLower() == ".xml")) 
                {
                    c.IncludeXmlComments(name, includeControllerXmlComments: true);
                }
            });

　　這里需要獲取APIversion中各個版本的信息，可以利用services.BuildServiceProvider().GetRequiredService<>獲取。

c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());

　　同時這句是為了讓swaager支持函數重載。而且可以通過OrderActionsBy來設置排序順序。

　　最后在Configure中使用swagger。

　　　　　　　　app.UseSwagger();
            
            var provider = _services.BuildServiceProvider().GetRequiredService<IApiVersionDescriptionProvider>();
            app.UseSwaggerUI(c =>
            {
                foreach (var item in provider.ApiVersionDescriptions) 
                {
                    c.SwaggerEndpoint($"/swagger/{item.GroupName}/swagger.json", item.GroupName);
                }
            });

　　為了獲取serviceCollection中的apiversion信息，需要添加如下;

private IServiceCollection _services;

　　在ConfigureServices中添加：

_services = services;

　　這樣就能在Configure中使用ServiceCollention中的service了。

結果：

　　

　　可以通過swagger中的definition來選擇接口版本，也能看到接口版本顯示先url中。