asp.net core swashbuckle 如何在同一个控制器中使用版本控制

Question

在 asp.net core 中使用带有 swashbuckle for swagger 的版本控制时，默认情况下不能在同一个控制器中使用多个方法，如下所示：

[Route("v{version:apiVersion}/[controller]")]
[ApiVersion("1")]
[ApiVersion("2")]
[ApiController]
public class TestController : ControllerBase
{
    /// <summary>
    /// test ver 1
    /// </summary>
    /// <returns></returns>
    [HttpGet]
    [MapToApiVersion("1")]
    [ProducesResponseType(StatusCodes.Status200OK)]
    public string Get()
    {
        return "Version 1";
    }

    /// <summary>
    /// test ver 2
    /// </summary>
    /// <returns></returns>
    [HttpGet]
    [MapToApiVersion("2")]
    [ProducesResponseType(StatusCodes.Status200OK)]
    public string Get2()
    {
        return "Version 2";
    }
}

Answer 1

When using versioning in asp.net core with swashbuckle for swagger, you cannot have by default multiple methods in same controller like that:

[Route("v{version:apiVersion}/[controller]")]
[ApiVersion("1")]
[ApiVersion("2")]
[ApiController]
public class TestController : ControllerBase
{
    /// <summary>
    /// test ver 1
    /// </summary>
    /// <returns></returns>
    [HttpGet]
    [MapToApiVersion("1")]
    [ProducesResponseType(StatusCodes.Status200OK)]
    public string Get()
    {
        return "Version 1";
    }

    /// <summary>
    /// test ver 2
    /// </summary>
    /// <returns></returns>
    [HttpGet]
    [MapToApiVersion("2")]
    [ProducesResponseType(StatusCodes.Status200OK)]
    public string Get2()
    {
        return "Version 2";
    }
}

By default, you will have error message

Swashbuckle.AspNetCore.SwaggerGen.SwaggerGeneratorException: Conflicting method/path combination "GET v{version}/Test" for actions

• ...Controllers.TestController.Get,...TestController.Get2

because swagger-ui recognized both methods by same route

localhost/v{version:apiVersion}/Test

Basic swashbuckle solution is to have two separate controllers for each version of method. That is bad solution for my use-case.

Answer 2

对于ASP.Net core 5及以上版本， 这在解决招摇文档问题，建议这样做，而不是编写自定义代码来生成特定版本的文档文章可以帮助