带有 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);
}

希望对您有所帮助。