c# - Swagger 找不到 ApiVersion ed 的操作

Question

我正在 ASP.NET Core 中构建一个 Web API，并且正在试验多个版本。我正在按照以下说明为每个版本创建 Swagger 文档:https://github.com/domaindrivendev/Swashbuckle.AspNetCore/blob/master/README.md#customize-the-action-selection-process

我有两个版本的相同 Action ，定义如下:

namespace Web.Api
{
    [ApiController]
    [Area("api")]
    [Route("[area]/[controller]")]
    public abstract class MyApiControllerBase : ControllerBase
    {

    }
}

namespace Web.Api.V1
{
    public class TestController : MyApiControllerBase
    {
        [HttpGet]
        [ApiVersion("1.0")]
        public IActionResult Get()
        {
            return Ok("Version 1.0 endpoint.");
        }
    }
}

namespace Web.Api.V2
{
    public class TestController : MyApiControllerBase
    {
        [HttpGet]
        [ApiVersion("2.0")]
        public IActionResult Get()
        {
            return Ok("Version 2.0 endpoint.");
        }
    }
}

我的 Swagger Gen 在 Startup.cs 中是这样配置的:

services.AddSwaggerGen(options =>
{
    options.DocInclusionPredicate((docName, apiDesc) =>
    {
        if (!apiDesc.TryGetMethodInfo(out MethodInfo methodInfo))
        {
            return false;
        }

        IEnumerable<ApiVersion> versions = methodInfo.DeclaringType
            .GetCustomAttributes(true)
            .OfType<ApiVersionAttribute>()
            .SelectMany(a => a.Versions);

        return versions.Any(v => $"v{v.ToString()}" == docName);
    });

    options.SwaggerDoc("v1.0", new OpenApiInfo { Title = "My API", Version = "v1.0" });
    options.SwaggerDoc("v2.0", new OpenApiInfo { Title = "My API", Version = "v2.0" });
});

但是，当我访问 Swagger UI 时，它显示“规范中未定义任何操作!”适用于 v1.0 和 v2.0。如果我检查 DocInclusionPredicate加载 Swagger 文档时，似乎 ApiVersion属性没有被选取，因此解释了为什么它们没有包含在文档中。例如，当 Web.Api.V2.TestController.Get被传递为 apiDesc参数，这是为 Attributes 找到的内容:

Attributes

只有 ApiControllerAttribute , AreaAttribute , RouteAttribute , 和 ControllerAttribute被发现。所有这些都是基类上的属性，而不是直接在 TestController 上的。或 Get()行动本身。

Answer 1

对于asp.net core 3.0，您可以按照以下步骤操作:

1.安装 Swashbuckle.AspNetCore 5.0.0

2.安装 Microsoft.AspNetCore.Mvc.Versioning 4.0.0

3.安装 Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer 4.0.0

4.改变你的 Controller 如下(ApiVersion需要在 Controller 上声明):

[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion("1.0")]
public class TestController : MyApiControllerBase
{
    [HttpGet]      
    public IActionResult Get()
    {
        return Ok("Version 1.0 endpoint.");
    }
}
[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion("2.0")]
public class TestController : MyApiControllerBase
{
    [HttpGet]        
    public IActionResult Get()
    {
        return Ok("Version 2.0 endpoint.");
    }
}

5.Startup.cs(注意需要使用services.AddVersionedApiExplorer并设置options.SubstituteApiVersionInUrl=true来告诉swagger替换 Controller 路由中的版本并配置api版本:):

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();

    services.AddApiVersioning(o => {
        o.ReportApiVersions = true;
        o.AssumeDefaultVersionWhenUnspecified = true;
        o.DefaultApiVersion = new ApiVersion(1, 0);
    });
    services.AddVersionedApiExplorer(o =>
    {
        o.GroupNameFormat = "'v'VVV";
        o.SubstituteApiVersionInUrl = true;
    });

    services.AddSwaggerGen(options =>
    {
        options.DocInclusionPredicate((docName, apiDesc) =>
        {
            if (!apiDesc.TryGetMethodInfo(out MethodInfo methodInfo))
            {
                return false;
            }

            IEnumerable<ApiVersion> versions = methodInfo.DeclaringType
                .GetCustomAttributes(true)
                .OfType<ApiVersionAttribute>()
                .SelectMany(a => a.Versions);

            return versions.Any(v => $"v{v.ToString()}" == docName);
        });

        options.SwaggerDoc("v1.0", new OpenApiInfo { Title = "My API", Version = "v1.0" });
        options.SwaggerDoc("v2.0", new OpenApiInfo { Title = "My API", Version = "v2.0" });
    });
}

// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    app.UseHttpsRedirection();
    app.UseApiVersioning();
    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1.0/swagger.json", "V1 Docs");
        c.SwaggerEndpoint("/swagger/v2.0/swagger.json", "V2 Docs");
    });

    app.UseRouting();

    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}