带有 Swagger 文档的可选 WebAPI 路由参数

Question

我有一个在属性中定义路由的 WebAPI 方法，有一个强制参数和一个可选参数：

    [HttpGet]
    [Route("api/ChargeCard/{cif}/{feeScheme=null}")]
    [ResponseType(typeof(ChargeCardRoot))]
    public IHttpActionResult Get(string cif, string feeScheme, ChargeCardRequestMode mode = ChargeCardRequestMode.Basic)
    {

我还使用 Swashbuckle / Swagger 来生成文档。 问题是 Swagger 总是将我的可选参数标记为必需。

将可选参数表示法更改为：

    [Route("api/ChargeCard/{cif}/{feeScheme?}")]

使这两个参数都像必需的一样，它也不会使 Swagger 将其显示为可选。

有没有办法使用 Swagger 为可选参数生成正确的文档？

Answer 1

如果您重载您的方法，Swashbuckle 将生成两个不同的 Swagger 端点。 一种方法有参数，另一种没有，并使用“缺失”参数的默认值调用第一个方法。 如果您使用 HyprLinkr 之类的东西来生成 HATEOAS 链接，这也有一个好处，因为您不能在表达式中使用可选参数。

[HttpGet]
[Route("api/ChargeCard/{cif}/{feeScheme}")]
[ResponseType(typeof(ChargeCardRoot))]
public IHttpActionResult Get(string cif, string feeScheme, ChargeCardRequestMode mode = ChargeCardRequestMode.Basic)
{
    // working code
}

[HttpGet]
[Route("api/ChargeCard/{cif}")]
[ResponseType(typeof(ChargeCardRoot))]
public IHttpActionResult Get(string cif, string feeScheme)
{
    return Get(cif, feeScheme, ChargeRequestMode.Basic);
}

希望有帮助。

Answer 2

就 Swagger 而言，您可以通过从路由中省略它们并指定“字符串？”来指定可选参数。 对于方法签名中的参数声明如下：

[HttpGet]
[Route("api/ChargeCard/{cif}")]
[ResponseType(typeof(ChargeCardRoot))]
public IHttpActionResult Get(string cif, string? feeScheme)
{
    ...
}

但是请注意，这些将不再作为路线的一部分传递。 可选参数将作为附加到路由的查询参数传递，如下所示：

https://somedomain.com/api/ChargeCard/{cif}?feeScheme=ABCD

如果您采用这种方法，您还需要将此行添加到文件的顶部，以防止 Visual Studio 删除“？” 并将其替换为 [CanBeNull] 属性：

#nullable enable