Swagger - Web API - Optional query parameters

Question

[HttpGet]
[Route("students")]
[SwaggerOperation(Tags = new[] { "Student" })]
[SwaggerResponse(HttpStatusCode.OK, Type = typeof(ResponseModel<IList<Student>>))]
[SwaggerResponseExample(HttpStatusCode.OK, typeof(StudentResponseExample))]
[SwaggerResponse(HttpStatusCode.InternalServerError)]
public IHttpActionResult SearchStudent()
    {
        IDictionary<string, string> searchParams = null;
        searchParams = ControllerContext.GetQueryStrings();
        .
        .
        .

    }

The above API has three optional parameters which will be pass as query string

1. SyncDate - Long
2. OffSet - int
3. Limit - int

There is no option for user to enter these optional query parameters in swagger UI. Please guide me to implement the optional query parameters.

I am using swashbuckle and I prefer to use annotations rather than having a lengthy comment section over each API method for swagger functionalities.

I referred the following Adding Query String Params to my Swagger Specs and created the SwaggerParameterAttribute class in Filters folder of Web API and when trying to add the OperationFilter in GlobalConfiguration.Configuration .EnableSwagger as given, it throws type or the namespace name SwaggerParametersAttributeHandler could not be found. I even added the Filters folder namespace but still the error exists.

Please guide on how to implement the optional query parameters in swagger

Roz

Answer 1

The way Swagger works it pulls out parameters based on your signature of Action i.e parameters to your Action, but here you are getting these value from ControllerContext which obviously Swagger will never be aware of.

So You need to change the signature of the Action and pass your parameters there.

They will be treated as optional if you make them of nullable type -

[HttpGet]
[Route("students")]
[SwaggerOperation(Tags = new[] { "Student" })]
[SwaggerResponse(HttpStatusCode.OK, Type = typeof(ResponseModel<IList<Student>>))]
[SwaggerResponseExample(HttpStatusCode.OK, typeof(StudentResponseExample))]
[SwaggerResponse(HttpStatusCode.InternalServerError)]
public IHttpActionResult SearchStudent(long? SyncDate = null,int? OffSet = null,int? Limit = null)
{
    // Use the variables here
    .
    .
    .

}

Shopworn

Thanks, but in swagger UI it is displays as required. how do I change it to optional? – Roz

@TechJerk Just updated my answer to assign null values to parameters and making them optional. – Shopworn

What about System.String which is reference type ? – Amatol

@Amatol Strings will be passed in as null, you don't have to do anything special. – Schizophyceous

for strings, you should also pass as SearchStudent(string name = null) so WebApi recognizes it as an optional parameters – Frizzell

What if the string is not top-level, but inside a class? – Boykin

Answer 2

This worked for me:

[System.Web.Http.HttpGet] 
[Route("api/DoStuff/{reqParam}")]  
[Route("api/DoStuff/{reqParam}/{optParam1:alpha?}/{optParam2:datetime?}")]
public string Get(string reqParam, string optParam1= "", string optParam2= "")

It did create two sections in my Swagger UI but that works for me.

Winonawinonah

This doesn't solve the issue. In swagger, optional parameters still shown as required. – Louisville

Answer 3

Try this:

[HttpGet("api/DoStuff/{reqParam}")]
public async Task<IActionResult> Get(string reqParam, string optParam1= "", string optParam2= "")

Hiatus