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

Question

I have a WebAPI method with routing defined in an attribute, having one mandatory parameter and one optional:

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

I also use Swashbuckle / Swagger to generate documentation. The problem is that Swagger always marks my optional parameter as required.

Changing optional parameter notation to:

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

makes both parameters acting like they are required, it doesn't make Swagger to show it as optional either.

Is there a way to generate correct documentation for optional parameters with Swagger?

Answer 1

If you overload your methods, Swashbuckle will generate two different Swagger endpoints. One method has the parameter, the other does not and calls the first one with the default value for the "missing" parameter. This also has the advantage of making it easier if you using something like HyprLinkr to generate HATEOAS links, as you can't have optional parameters in an expression.

[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);
}

Hope that helps.

Answer 2

As far as Swagger is concerned, you could specify optional parameters by omitting them from the route and specifying "string?" for the parameter declarations in the method signature as follows:

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

Note however, that these would no longer get passed as part of the route. The optional parameters would get passed as query parameters appended to the route, as follows:

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

If you take this approach, you would also need to add this line to the top of your file to prevent Visual Studio from removing the "?" and replacing it with [CanBeNull] attribute:

#nullable enable