How to document an optional QueryString parameter in ASP.NET WebApi help pages?

Question

The ASP.Net Web Api help pages appear to automatically determine if the parameter is in a Uri or Body request. How can I document parameter parameters that are QueryString parameters?

For example, I may have a RESTful Url, for example

[GET] api/Books?relatedToBookId=xx 

Where "relatedToBookId" is an optional queryString parameter.

Usually parameters that are FromUri or FromBody are put in comments as

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

Answer 1

You can do the following, and your additional information about the query string parameters will appear in HelpPage.

In the code below, relatedToBookId is an optional parameter coming from the 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) 

In addition, if you want to indicate that this parameter is optional, you can do the following:

• Go to the setup 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;