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!

Answer 1

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.