WebAPI Help Page - Documentation for return or parameter model/class properties

Question

I am using Web API Help Page with Web API 2 (5.0) - both the latest Nuget packages. I would like the help documentation to show the comments of the properties on classes that are parameters or returned in the body of the HttpResponseMessage.

For example, I have a controller method like this:

public HttpResponseMessage Post([FromBody] MyClassType1 myClass)
{
    // Business logic removed for clarity
    return Request.CreateResponse(HttpStatusCode.OK, new MyClassType2());
}

I would like the XML comments that I have on MyClassType1 and MyClassType2 to be displayed on the help page for the above post action.

Everywhere I have looked, so far it appears that this is not yet supported. However, I am wondering if anyone has been able to get this to work by extending ApiExplorer, adding to XmlDocumentationProvider, etc?

I know that the comments and properties are included in the XML file that gets generated, so I could try to parse that manually (all the parameter and return types are in the MyAssemblyName.Models namespace, so my thought was I could look for the XML nodes that have a member name starting with that namespace. However, I know the built-in web API help pages have some caching features, so I prefer to somehow incorporate this with the existing functionality (just add on to it).

I have managed to show the types of the parameters (one layer down only) by updating the Parameters.cshtml template to this:

@using System.Reflection
@using System.Threading
@using System.Web.Http.Description
@using Regency.API.Services.Areas.HelpPage
@model System.Collections.ObjectModel.Collection<ApiParameterDescription>

<table class="help-page-table">
    <thead>
        <tr><th>Name</th><th>Properties</th><th>Description</th><th>Additional information</th></tr>
    </thead>
    <tbody>
        @foreach (ApiParameterDescription parameter in Model)
        {
            string parameterDocumentation = parameter.Documentation ?? "No documentation available.";
            Type parameterType = parameter.ParameterDescriptor.ParameterType;

            // Don't show CancellationToken because it's a special parameter
            if (!typeof (CancellationToken).IsAssignableFrom(parameter.ParameterDescriptor.ParameterType))
            {
                <tr>
                    <td class="parameter-name"><b>@parameter.Name</b></td>
                    <td class="parameter-properties">
                        @foreach (PropertyInfo property in parameterType.GetProperties())
                        {
                            <text>@property.Name : @property.PropertyType.GetFriendlyTypeName()</text>
                            <br/>
                        }
                    </td>
                    <td class="parameter-documentation"><pre>@parameterDocumentation</pre></td>
                    <td class="parameter-source">
                        @switch(parameter.Source)
                        {
                            case ApiParameterSource.FromBody:
                                <p>Define this parameter in the request <b>body</b>.</p>
                                break;
                            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;
                            default:
                                <p>None.</p>
                                break;
                        }
                    </td>
                </tr>
            }
        }
    </tbody>
</table>

where the GetFriendlyTypeName() method above is implemented as shown here: How can I get the correct text definition of a generic type using reflection?

However, this doesn't get me the comments from these classes and it doesn't help with nested types (e.g. if my model had a complex-typed property on it, it would not show the properties of that complex-typed property). And the types are not useful enough without their XML comments anyway.

Also, this only applies to parameters, but not to return types contained in the body of the HttpResponseMessage. I was able to get the response samples to work by implementing a ResponseTypeAttribute as shown here: Auto generated help pages with return type HttpResponseMessage but again that doesn't give me the properties with XML comments. I could use reflection to get the types similarly to how I got the parameter types again, but I really would like the XML comments together with types, and including nested complex types.

I would also find it acceptable to document the model/class documentation (properties with types and XML comments) separately from the service calls, and have the service calls just show the name of the type that they return (then at least the user could find the documentation for that type).

Has anyone been able to implement something similar to what I am trying to do for either parameters or return types, preferably both? Or any ideas to point me in the right direction?

Lorenza

Answer 1

The feature of documenting individual properties of a complex type is currently in development and would be available for next release. That said you can currently get the HelpPage package from the Nightly builds and try it. You should be able to upgrade this package onto an existing 5.0 web api project.

Also currently we document only the action's input types and not the response types as generally users would want to know about the input types's information. But I can see that users might want the response type's information for consumption too...we will look into this and will let you know.

Aut

Thank you, Kiran. When is the next release planned? I think that documenting the response types would be an important aspect to include with an API and hope that this functionality makes it into the next release as well. Is there a blog or forum post to follow for new features like this being added? – Lorenza

I am not authorized to reveal the release dates :-)...but I can surely say that this functionality will be available in next release. We are currently doing some final touches to this feature and would probably blog about it then... – Aut

Has this functionality shipped in v5.1.2 or a nightly? The Help Pages are still not picking up my model's property xml comments. – Teeny

Answer 2

You can make modifications to allow html in documentation comments Here is a Reference.

After you allow HTML you can put a table with property information where the XML documentation param tag description goes. You can also look at a help page HTML source to get the class attribute names that are being used for help page tables so your table will use the same CSS as all the other tables.

This is a hack but it works perfectly.

Saying