当参数未命名为 id 时，使用 Swashbuckle 的 Swagger 不会生成文档

Question

在 .NET 4.8 上的 ASP.NET MVC 应用程序中，我使用 Swagger 和 Swashbuckle 来生成 API 文档。自动生成适用于某些端点，而不是所有端点。

例如，当我有像

test(int id)

这样的端点时，文档会正确生成。当我有自定义命名的参数时，例如

test(int ids)

，不会生成任何内容。知道为什么吗？

我尝试了参数的各种名称，但只要它不是

id

，文档就不会生成

更新：

这是我正在使用的控制器的示例（我伪造了该示例以不提供真正的实际代码）：

public class FakeController : ApiController
    {
        /// <summary>
        /// This is postint2
        /// </summary>
        /// <param name="id"></param>
        /// <returns></returns>
        public int Post(int id)
        {
            return 0;
        }

        /// <summary>
        /// Post2 
        /// </summary>
        /// <param name="ids"></param>
        /// <returns></returns>
        // GET: api/items/post2/{ids}
        public int Post2(int ids)
        {
            return 0;
        }

        /// <summary>
        /// This is postint2
        /// </summary>
        /// <param name="id"></param>
        /// <returns></returns>
        public int Post3(int id)
        {
            return 0;
        }
    }

我的路线如下：

config.Routes.MapHttpRoute(
                name: "DefaultApi",
                routeTemplate: "{controller}/{id}/{action}",
                defaults: new { id = RouteParameter.Optional, action = RouteParameter.Optional }
            );

在此示例中，未生成端点 Post2 文档。可能是因为参数“ids”与我使用的默认路由不匹配？

如何在不更改其余代码行为的情况下生成该 Post2 的文档？我不想更改路由或以任何方式影响端点，因为此代码已经在生产中大量使用。

Answer 1

无需更改中间件/路由配置，您只需将 Route 属性添加到控制器方法中，以便 Swagger 可以正确识别和解析它们，就像这样......

public class FakeController : ApiController
{
    /// <summary>
    /// This is postint2
    /// </summary>
    /// <param name="id"></param>
    /// <returns></returns>
    public int Post(int id)
    {
        return 0;
    }

    /// <summary>
    /// Post2 
    /// </summary>
    /// <param name="ids"></param>
    /// <returns></returns>
    [Route("api/items/post2/{ids}")]
    public int Post2(int ids)
    {
        return 0;
    }

    /// <summary>
    /// This is postint2
    /// </summary>
    /// <param name="id"></param>
    /// <returns></returns>
    public int Post3(int id)
    {
        return 0;
    }
}

在Post2方法中添加

[Route]

属性，可以确保Swagger能够正确识别路由并生成文档。这样，您不需要更改默认路由配置或影响现有端点。