CODEWITHSUNDEEP
c#xmldocumentationquery-stringswashbuckle
Chris Nelson
Chris Nelson

Reputation: 3707

How can I document query string parameters with Swashbuckle?

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?

Upvotes: 2

Views: 3917

Answers (1)

Chris Nelson
Chris Nelson

Reputation: 3707

@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;

Upvotes: 2

Related Questions