CODEWITHSUNDEEP
c#asp.net-web-apiroutesswagger
Tomasz Przychodzki
Tomasz Przychodzki

Reputation: 691

Optional WebAPI routing parameters with Swagger documentation

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?

Upvotes: 6

Views: 9243

Answers (2)

Elan
Elan

Reputation: 6376

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

Upvotes: -1

MichaelDotKnox
MichaelDotKnox

Reputation: 1310

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.

Upvotes: 6

Related Questions