动作的方法/路径组合冲突-Swagger无法区分备用版本与Route

问题描述

我的解决方案中具有以下控制器设置：

[Route("api/v{VersionId}/[controller]")]
[ApiController]
[Produces("application/json")]
[Consumes("application/json")]
public class MyBaseController : ControllerBase
{
}


[ApiVersion("1.0")]
[ApiVersion("1.1")]
public class AuthenticationController : MyBaseController
{
    private readonly ILoginService _loginService;

    public AuthenticationController(ILoginService loginService)
    {
        _loginService = loginService;
    }

    [ProducesResponseType(StatusCodes.Status200OK)]
    [ProducesResponseType(StatusCodes.Status403Forbidden)]
    [ProducesResponseType(StatusCodes.Status404NotFound)]
    [ProducesResponseType(StatusCodes.Status500InternalServerError)]
    [ProducesResponseType(StatusCodes.Status400BadRequest)]
    [HttpPost("login")]
    public ActionResult<v1.JwtTokenResponse> Login([FromBody] v1.LoginRequest loginRequest)
    {
        var loginResult = _loginService.Login(loginRequest.Email,loginRequest.Password);
        if (loginResult.StatusCode != HttpStatusCode.OK)
        {
            return StatusCode((int)loginResult.StatusCode);
        }

        var tokenResponse = new v1.JwtTokenResponse() { Token = loginResult.Token };

        return Ok(tokenResponse);
    }
}

在我的API的两个版本之间，此方法没有任何更改，因此从逻辑上讲，我希望在文档中显示新版本仍支持该方法。让我们争辩说，我们的第二个客户控制者的逻辑发生了变化，因此这就是为什么我们使用新版本1.1的原因，因为语义版本控制要求添加新内容，但是是以向后兼容的方式。

运行此代码时，自然一切正常。该代码是有效的，并且.net核心允许这种实现，但是，当涉及到swagger gen时，我遇到了问题，并产生了以下错误：

NotSupportedException: Conflicting method/path combination "POST api/v{VersionId}/Authentication/login" for actions - Template.Api.Endpoints.Controllers.AuthenticationController.Login (Template.Api.Endpoints),Template.Api.Endpoints.Controllers.AuthenticationController.Login (Template.Api.Endpoints). Actions require a unique method/path combination for Swagger/OpenAPI 3.0. Use ConflictingActionsResolver as a workaround

如您在上面看到的，路径是不同的，因为传递到路由中的version参数使之变为这种方式。此外，仅仅创建一个新方法来纯粹表示代码可通过文档获得是没有意义的，所以，我的问题是为什么大张旗鼓地忽略路径中的版本差异并建议使用ConflictingActionsResolver的用户？

此外，在深入研究这一问题之后，发现很多其他人都遇到了同样的问题（标头版本化是社区的一个特殊错误，而Swaggers硬线方法与此冲突），通用方法似乎要使用冲突的动作解析器仅采用它遇到的第一个描述，该描述只会在api文档中公开1.0版，而忽略1.1版，这在Swagger中给人的印象是没有可用的终结点1.1版。 / p>

Swagger UI Config

app.UseSwaggerUI(setup =>
{
   setup.RoutePrefix = string.Empty;

   foreach (var description in apiVersions.ApiVersionDescriptions)
   {
      setup.SwaggerEndpoint($"/swagger/" +
                            $"OpenAPISpecification{description.GroupName}/swagger.json",description.GroupName.toupperInvariant());
   }

});

我们如何解决这个问题并正确显示Swagger中的可用端点，而不必创建有效地导致代码重复的新方法，而仅仅是为了满足Swagger规范中的疏忽？任何帮助将不胜感激。

许多人可能会建议在路线的末尾添加操作，但是我们希望避免这种情况，因为这意味着我们想要通过GET，POST，PUT属性派生CRUD操作来争取客户/ 1之类的端点时，会感到不安无需附加诸如customer / add_customer_1或customers / add_customer_2之类的内容，以在URL中反映方法名称。

解决方法

这是我在使用Picker时的Swagger设置。

HeaderApiVersionReader

在Startup＃ConfigureServices

public class SwaggerOptions
{
    public string Title { get; set; }
    public string JsonRoute { get; set; }
    public string Description { get; set; }
    public List<Version> Versions { get; set; }

    public class Version
    {
        public string Name { get; set; }
        public string UiEndpoint { get; set; }
    }
}

在Startup＃Configure

中

        // Configure versions 
        services.AddApiVersioning(apiVersioningOptions =>
        {
            apiVersioningOptions.AssumeDefaultVersionWhenUnspecified = true;
            apiVersioningOptions.DefaultApiVersion = new ApiVersion(1,0);
            apiVersioningOptions.ReportApiVersions = true;
            apiVersioningOptions.ApiVersionReader = new HeaderApiVersionReader("api-version");
        });

        // Register the Swagger generator,defining 1 or more Swagger documents
        services.AddSwaggerGen(swaggerGenOptions =>
        {
            var swaggerOptions = new SwaggerOptions();
            Configuration.GetSection("Swagger").Bind(swaggerOptions);

            foreach (var currentVersion in swaggerOptions.Versions)
            {
                swaggerGenOptions.SwaggerDoc(currentVersion.Name,new OpenApiInfo
                {
                    Title = swaggerOptions.Title,Version = currentVersion.Name,Description = swaggerOptions.Description
                });
            }

            swaggerGenOptions.DocInclusionPredicate((version,desc) =>
            {
                if (!desc.TryGetMethodInfo(out MethodInfo methodInfo))
                {
                    return false;
                }
                var versions = methodInfo.DeclaringType.GetConstructors()
                    .SelectMany(constructorInfo => constructorInfo.DeclaringType.CustomAttributes
                        .Where(attributeData => attributeData.AttributeType == typeof(ApiVersionAttribute))
                        .SelectMany(attributeData => attributeData.ConstructorArguments
                            .Select(attributeTypedArgument => attributeTypedArgument.Value)));

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

            swaggerGenOptions.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory,$"{Assembly.GetExecutingAssembly().GetName().Name}.xml"));
            
            ... some filter settings here 
        });

appsettings.json

var swaggerOptions = new SwaggerOptions();
Configuration.GetSection("Swagger").Bind(swaggerOptions);
app.UseSwagger(option => option.RouteTemplate = swaggerOptions.JsonRoute);

app.UseSwaggerUI(option =>
{
  foreach (var currentVersion in swaggerOptions.Versions)
  {
    option.SwaggerEndpoint(currentVersion.UiEndpoint,$"{swaggerOptions.Title} {currentVersion.Name}");
  }
});

,

有两个问题。

第一个问题是路由模板不包含路由约束。按URL段进行版本控制时，这是必需的。

因此：

[Route("api/v{VersionId}/[controller]")]

应该是：

[Route("api/v{VersionId:apiVersion}/[controller]")]

许多示例将显示使用version作为路由参数名称，但是您可以使用VersionId或所需的任何其他名称。

第二个问题是您可能正在创建一个OpenAPI / Swagger文档。该文档要求每个路由模板都是唯一的。 Swashbuckle中的默认行为是每个API版本的文档。此方法将产生唯一的路径。如果确实只需要一个文档，则可以使用URL段版本控制，但是您需要扩展路由模板，以便它们生成唯一的路径。

确保您的API Explorer配置具有：

services.AddVersionedApiExplorer(options => options.SubstituteApiVersionInUrl = true);

这将产生将api/v{VersionId:apiVersion}/[controller]分别扩展到api/v1/Authentication和api/v1.1/Authentication的路径。