ASP.NET Core 设置默认 API 版本控制。

Question

我正在使用Asp.Net Core作为Rest API服务。我需要进行API版本控制。实际上，在启动时，我设置了以下设置，它可以正常工作，但是当我将其设置为默认版本时，它不起作用。

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

在控制器中设置属性，方法如下： 版本1：

[ApiController]
[Route("v{version:apiVersion}/[controller]")]
[ApiVersion("1.0")]
public class UsersController : ControllerBase
{
    [HttpGet("log")]
    public string Get()
    {
        return $"{DateTime.Now}";
    }
}

版本 2：

[ApiController]
[Route("v{version:apiVersion}/[controller]")]
[ApiVersion("2.0")]
public class UsersController : ControllerBase
{
    [HttpGet("log")]
    public string Get()
    {
        return $"{DateTime.Now}";
    }
}

我可以得到以下结果链接：

http://localhost:5000/v1/users/log => 状态码：200

http://localhost:5000/v2/users/log => 状态码：200

但是http://localhost:5000/users/log => 状态码：404

如何在版本控制中设置默认API？

感谢大家抽出时间来尝试帮助解释。

- Saeid Mirzaei

Answer 1

如果没有指定默认的API版本，则您的配置会正确设置默认的API版本。但是，您的路由要求请求URL包括v{version}部分。因此，一种可能的解决方案是添加另一个没有v{version}的路由，就像这样：

[ApiController]
[Route("v{version:apiVersion}/[controller]")]
[Route("/[controller]")]
[ApiVersion("1.0")]
public class UsersController : ControllerBase
{
    [HttpGet("log")]
    public string Get()
    {
        return $"{DateTime.Now}";
    }
}

现在请求 http://localhost:5000/users/log 将指向带有 API 版本 1.0 的控制器。如果你将此路由添加到第二个控制器，版本 1.0 仍将被选中，因为默认的 ApiVersion 将被选择，它是 1.0。

- Alexander

---

感谢您的指导，如果我在控制器中添加一个新路由，Swagger文档中就会出现一个新的路由。 - Saeid Mirzaei

@SaeidMirzaei 我的帖子回答了你发布的问题。请更新它或创建一个新的帖子来解决新的问题。关于 Swagger 中的新路由，我不知道如何防止这种情况，恐怕你需要选择另一个版本控制的路由模板，但我不确定。 - Alexander

这是正确的答案。@SaeidMirzaei，你所要求的是不可能实现的。你不能期望 /api/values/{id}/subvalues 在没有 {id} 参数的情况下正常工作。当你通过 URL 段进行版本控制时，情况也是如此。AssumedDefaultVersionWhenUnspecified 不是为解决这个问题而设计的，这也是为什么通过 URL 段进行版本控制是最不符合 RESTful 方法的另一个例子。需要进行双重路由注册。要过滤 OpenAPI/Swagger 文档生成，可以使用自定义的 IApiDescriptionProvider 或 IOperationFilter（对于 Swashbuckle）。 - Chris Martinez