Optional WebAPI routing parameters with Swagger documentation

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?

Hammad S. · Accepted Answer · 2019-05-30 11:59:24Z

6

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.

edited May 30, 2019 at 11:59

Hammad S.

3061 gold badge3 silver badges14 bronze badges

answered Feb 28, 2017 at 22:57

MichaelDotKnox

1,3081 gold badge14 silver badges17 bronze badges

Sign up to request clarification or add additional context in comments.

3 Comments

Tomasz Przychodzki Over a year ago

Thanks, almost there :) I just had to remove feeScheme argument from the overloaded method and inside it call the other with null value, and that makes Swashbucle to generate two endpoints, and both can be now tested on Swagger page. But still, this is more like a workaround then the solution. Does it mean Swagger cannot show routing parameters as optional at all?

MichaelDotKnox Over a year ago

I don't believe you can specify optional parameters the way you are trying to do them. The problem is really the route, as it doesn't really support optional parameters that way. The parameters is the route are really separate from the parameters of the method.

JStevens Over a year ago

This must explain why Swagger does not except optional parameters. Overload is a much cleaner way to go... imho

Elan · Accepted Answer · 2022-09-02 11:22:38Z

-1

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

edited Sep 2, 2022 at 11:22

answered Sep 2, 2022 at 11:10

Elan

6,40613 gold badges68 silver badges88 bronze badges

Collectives™ on Stack Overflow

Optional WebAPI routing parameters with Swagger documentation

2 Answers 2

3 Comments

Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

3 Comments

Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related