How can I document query string parameters with Swashbuckle?

Question

Swashbuckle does a great job of extracting C# XML comments to make Swagger API documentation. And Swagger supports documenting query string parameters. But if there's a way to document query string parameters in XML so Swashbuckle will export them, I haven't found it.

I have something like:

    /// <summary>
    /// List all users
    /// </summary>
    /// <param name="?search">String to search for in user IDs and names</param>
    /// <returns>An array of users</returns>
    /// <response code="200">OK</response>
    [ResponseType(typeof(IEnumerable<User>))]
    [Route("")]
    [HttpGet]
    public IHttpActionResult ListUsers()
    {
        IEnumerable<User> users;

        // "?search=<substring>" in the URI searches for users
        // Adapted from https://stackoverflow.com/questions/10656841
        var searchString = Request.GetQueryNameValuePairs()
            .Where(nv => nv.Key == "search")
            .Select(nv => nv.Value)
            .DefaultIfEmpty("")
            .FirstOrDefault();

And search does not show up in the output. I tried removing the ? and that didn't help. I suspect that the XML comments just don't support this directly. If that's true, I'm looking for a Best Practice work around. I'm considering adding a couple of bullets in a <remarks> block. Any better ideas?

Is there a reason you can't add a search parameter to the ListUsers method? — Sefe
– Sefe, Commented Dec 18, 2017 at 14:31
If there is a way to add query string parameters as optional parameters to the ListUsers() method that could work but I'm relatively new to C#.Net and don't know (how) to do that. — Chris Nelson
– Chris Nelson, Commented Dec 18, 2017 at 14:39
public IHttpActionResult ListUsers(string search) should do the trick. It will be set from the query string. — Sefe
– Sefe, Commented Dec 18, 2017 at 14:42
There's a similar problem (and solution): stackoverflow.com/questions/35828328/… — jps
– jps, Commented Dec 18, 2017 at 15:06

Chris Nelson · Accepted Answer · 2017-12-18 16:10:35Z

2

@jps pointed me in the right direction. Thanks!

I ended up with:

    /// <summary>
    /// List all users
    /// </summary>
    /// <param name="search">String to search for in user IDs and names</param>
    /// <returns>An array of users</returns>
    /// <response code="200">OK</response>
    [ResponseType(typeof(IEnumerable<User>))]
    [Route("")]
    [HttpGet]
    public IHttpActionResult ListUsers([Optional]string search)
    {
        IEnumerable<User> users;

        var searchString = search == null ? string.Empty : search;

answered Dec 18, 2017 at 16:10

Chris Nelson

3,7277 gold badges44 silver badges54 bronze badges

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

Collectives™ on Stack Overflow

How can I document query string parameters with Swashbuckle?

1 Answer 1

Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related