如何解决动作的方法/路径组合冲突-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的路径。
版权声明：本文内容由互联网用户自发贡献，该文观点与技术仅代表作者本人。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如发现本站有涉嫌侵权/违法违规的内容， 请发送邮件至 dio@foxmail.com 举报，一经查实，本站将立刻删除。