How do I document an optional QueryString parameter in ASP.NET WebApi Help Pages?

Question

The ASP.Net Web Api Help Pages seem to automatically determine if a parameter is in the Request Uri or Body. How can I document option parameters that are QueryString parameters?

For example I have may have a RESTful Url such as

[GET] api/Books?relatedToBookId=xx

Where "relatedToBookId" is an optional queryString parameter.

Normally the parameters that are FromUri or FromBody are put into the comments as

<param name="variableName">blah blah</param>

Tailstock

Answer 1

You could do the following and your optional query string parameter info would show up in the HelpPage.

In the below code relatedToBookId is an optional parameter coming from Query String.

    /// <summary>
    /// Gets list of books
    /// </summary>
    /// <param name="relatedToBookId">Your description here</param>
    /// <returns>returns list of books</returns>
    public IEnumerable<Book> GetBooks(int? relatedToBookId = null)

Also, if you would like to mention about this parameter being optional, you can do the following:

• Go to the installed file (Areas/HelpPage/Views/Help/DisplayTemplates/Parameters.cshtml)

• Update the condition related to case ApiParameterSource.FromUri to the following:

  case ApiParameterSource.FromUri: <p>Define this parameter in the request <b>URI</b>.</p> if(parameter.ParameterDescriptor.IsOptional) { <p>This parameter is <b>optional</b>.</p> } break;

Cunningham

Thank you, Kiran! Is there any way to have two separate help pages: e.g. one for "api/Books" and one for "api/Books?relatedToBookId=xx"? – Frantic