XML Comments for route parameters

Question

I am implementing a Web API project that will use the standard HelpPages area for documentation. I am using attribute routing and implemented ApiVersioning in my project. I've got most of my methods and models documented, however I am trying to figure out how to document the API version route parameter. Here is a example of my Controller:

/// <summary>
/// Controller for the License api.
/// </summary>
[ApiVersion("1.0")]
[RoutePrefix("api/v{version:apiVersion}/license")]
public class LicenseController : ApiController
{
    #region Software License Methods

    /// <summary>
    /// Creates a new Software License.
    /// </summary>
    /// <param name="value">The parameters for the license.</param>
    /// <returns>The newly created Activation and Emergency Ids.</returns>        
    [Route("software")]
    [HttpPost]
    public LicenseCreateResponse CreateSoftwareLicense([FromBody] CreateSoftwareLicenseRequest value)
    {
       // License creation code
    }

After configuring the HelpArea and running the project, I get the following help info:

There is a description available for the version parameter, however I don't know how to document it. It's not part of the route as far as the method is concerned, so trying <param name="version">... is fruitless.

Thanks for any help!

CodeFuller · Answer 1 · 2018-03-18T15:57:25.007

URI Parameters section on action help page is intended for description of action parameters that are bind from the URI query string (e.g. ...?SomeParam=SomeValue). In your case version is just a part of URI path that is not related to action parameters. So having it described in URI Parameters section could be confusing. That's why I propose to remove it from this section and (if required) put description for version template to some other section of help page.

To achieve this you should:

Remove version from URI Parameters list. This step is not trivial because version from route template is recognized by ApiExplorer as action parameter. Suppressing it will require modification of generated code that fills a model for API help page (HelpPageApiModel). This code resides in HelpPageConfigurationExtensions.GenerateUriParameters() method. Find the following lines:

Debug.Assert(parameterDescriptor == null);
// If parameterDescriptor is null, this is an undeclared route parameter which only occurs
// when source is FromUri. Ignored in request model and among resource parameters but listed
// as a simple string here.
ModelDescription modelDescription = modelGenerator.GetOrCreateModelDescription(typeof(string));
AddParameterDescription(apiModel, apiParameter, modelDescription);

and add condition for version parameter:

Debug.Assert(parameterDescriptor == null);

if (apiParameter.Documentation == null && String.Equals(apiParameter.Name, "version", StringComparison.InvariantCulture))
{
    continue;
}

// If parameterDescriptor is null, this is an undeclared route parameter which only occurs
// when source is FromUri. Ignored in request model and among resource parameters but listed
// as a simple string here.
ModelDescription modelDescription = modelGenerator.GetOrCreateModelDescription(typeof(string));
AddParameterDescription(apiModel, apiParameter, modelDescription);

Now you'll get the following help page:

Add specific section for version URI template:

Open view file Areas\HelpPage\Views\Help\DisplayTemplates\HelpPageApiModel.cshtml and add version section that you want. For example:
```
...

<h2>Request Information</h2>

<h3>Version info</h3>
Put some info about version here.

<h3>URI Parameters</h3>
@Html.DisplayFor(m => m.UriParameters, "Parameters")

...
```
Such view will give you:

If however you want to see version description in URI Parameters section, you could return to HelpPageConfigurationExtensions.GenerateUriParameters() method and replace above code with the following:

Debug.Assert(parameterDescriptor == null);

if (apiParameter.Documentation == null && String.Equals(apiParameter.Name, "version", StringComparison.InvariantCulture))
{
    apiParameter.Documentation = "Put description for version parameter here.";
}

// If parameterDescriptor is null, this is an undeclared route parameter which only occurs
// when source is FromUri. Ignored in request model and among resource parameters but listed
// as a simple string here.
ModelDescription modelDescription = modelGenerator.GetOrCreateModelDescription(typeof(string));
AddParameterDescription(apiModel, apiParameter, modelDescription);

This will give you:

Well, these approaches are not perfect (I'm not a fan of modifying generated HelpPageConfigurationExtensions). But seems like there is no other way to suppress or fill description for version parameter.

score 1 · Accepted Answer · answered Mar 26 '18 at 00:55

This solution might work, but it doesn't need to be that difficult. Out of curiosity are you using the official API Explorer package for API versioning? It would appear not. The IApiExplorer implementation it provides documents the API version parameter for you, including a description.

Should you want to change the default description text provided out-of-the-box, you can easily do so in the API Explorer options like so:

configuration.AddVersionedApiExplorer(
    options => options.DefaultApiVersionParameterDescription = "The version" )

Help Pages have seemingly gone out of style in favor of Swagger/Swashbuckle, but the API Versioning API explorer should work seamlessly with it. If there are gaps or other pain points, I'd definitely be interested in hearing about them.

XML Comments for route parameters

2 Answers2