How do I provide a definition for my Azure Function C# swagger UI GET parameter

Question

I am working on writing swagger for some azure functions written in C#, but can't figure out how to add an example parameter or a definition for what the parameter should be. My code as written looks like this, and does properly take in my inputs and run correctly based on them.

public async Task<HttpResponseMessage> Run(
        [HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = "GetCustomersInQueuesAndField/{companyId}/{branchId}/waitingfields/{waitingFields}/calledfields/{calledFields}")] HttpRequestMessage req,
        [CosmosDB(databaseName: "COSMOS:DATABASE",
           collectionName: "COSMOS:LATCH_TRIGGER_ITEMS_CONTAINER",
           ConnectionStringSetting = "COSMOS:CONNECTION_STRING"
        )]DocumentClient client,
        string companyId,
        string branchId,
        string waitingFields,
        string calledFields,
        ILogger log)

But Swagger generated is very basic:

I want to be able to add a definition of what is expected so a user can better understand what an input can be like so:

I can't figure out how to properly do this in Swagger though.

Answer 1

You can add parameter description as an XML comment, like so:

/// <param name="id">Here is the description for ID.</param>
[ProducesResponseType(typeof(Bar), (int)HttpStatusCode.OK)]
[HttpGet, Route("{id}", Name = "GetFoo")]
public async Task<IActionResult> Foo([FromRoute] long id)
{
    var response = new Bar();
    return Ok(response);
}

But it does require the following conditions to be met:

• XML comments must be enabled and configured with Swagger
• Parameters should be explicitly decorated with either [FromRoute], [FromQuery], [FromBody] etc.
• The same for the method type (get/post/put etc.), which should be decorated with [Http...]
• Parameter should be described with the a <param ...> xml comment