Documenting descriptions on Complex Types

Question

Within my API I'm trying to document the different field descriptions, however none of attributes seem to work. I know this functionality is supposed to have been recently implemented within WebAPI 5.1 (running WebAPI.HelpPage 5.1.2).

ASP.Net Web API Help Pages: Document Model Data Annotations - Work Item 877

I'm trying to document both my response model:

And the individual fields/properties

I've tried a mixture of XML comments, DataMember and Display attributes but none seem to be picked up.

/// <summary>
/// blah blah blah
/// </summary>
[DataContract(Name = "Application")]
public class Application
{
    /// <summary>
    /// Please Display!
    /// </summary>
    [DataMember(Order = 0)]
    [Display(Description="Please Display!")]
    [StringLength(11, MinimumLength = 11)]
    public string ApplicationId { get; set; }

Here is a sample from my Areas/HelpPage/App_Start/HelpPageConfig.cs

namespace WebAPI.Areas.HelpPage
{
    #pragma warning disable 1591
    /// <summary>
    /// Use this class to customize the Help Page.
    /// For example you can set a custom <see cref="System.Web.Http.Description.IDocumentationProvider"/> to supply the documentation
    /// or you can provide the samples for the requests/responses.
    /// </summary>
    public static class HelpPageConfig
    {
        public static void Register(HttpConfiguration config)
        {
            // remove unwanted formatters
            config.Formatters.Clear();
            var jsonsettings = new JsonSerializerSettings() { DateParseHandling = DateParseHandling.None };
            config.Formatters.Add(new JsonMediaTypeFormatter());
            config.Formatters.Add(new XmlMediaTypeFormatter());
            config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/bin/WebAPI.XML")));
            // create sample objects
            config.SetSampleObjects(new Dictionary<Type, object>
            {
                { typeof(MyResponse), new MyResponse() { 
                    Message = "Key d795677d-6477-494f-80c5-874b318cc020 is not recognised", 
                    Code = ResponseCode.InvalidKey, Id = null }
                }
            });             
            //*** More Sample Requests ***
        }
    }
    #pragma warning restore 1591
}

Update 10/06/2014: My class definitions are stored in a separate library. I've noticed a discrepancy here. The main API and class definition library were generating separate XML files.

API Project

Definition Project

I've attempted to rectify this by making the Definition write to the same XML project. However this doesn't work, and the class definition entries aren't added.

East

Can you share how your Areas\HelpPage\HelpPageConfig.cs looks like? – Joktan

I've added a snippet of my HelpPageConfig.cs – East

Thanks...i would first check if the file WebAPI.XML indeed has the xml comments that you decorated the properties..we by defualt do not support the text present in Display attribute... – Joktan

possible duplicate of How can Xml Documentation for Web Api include documentation from beyond the main project? – Manche

Answer 1

To have a content displayed in Description section you need to feel section of XML comments. If you would have your model class placed inside your webapi project - then this would be a solution. Your problem is that you need to read xml documentation form 2 xml files and one time and XmlDocumentationProvider does not support that. My suggestion is to create your own MultipleFilesXmlDocumentationProvider with a little effort like this:

public class MultipleFilesXmlDocumentationProvider : IDocumentationProvider
{
    IEnumerable<XmlDocumentationProvider> xmlDocumentationProviders;

    public MultipleFilesXmlDocumentationProvider(IEnumerable<string> documentPaths)
    {
        xmlDocumentationProviders = documentPaths.Select(path => new XmlDocumentationProvider(path));
    }

    public string GetDocumentation(HttpParameterDescriptor parameterDescriptor)
    {
        foreach(XmlDocumentationProvider provider in xmlDocumentationProviders)
        {
            string documentation = provider.GetDocumentation(parameterDescriptor);
            if(documentation != null)
                return documentation;
        }
        return null;
    }

    public string GetDocumentation(HttpActionDescriptor actionDescriptor)
    {
        foreach (XmlDocumentationProvider provider in xmlDocumentationProviders)
        {
            string documentation = provider.GetDocumentation(actionDescriptor);
            if (documentation != null)
                return documentation;
        }
        return null;
    }

    public string GetDocumentation(HttpControllerDescriptor controllerDescriptor)
    {
        foreach (XmlDocumentationProvider provider in xmlDocumentationProviders)
        {
            string documentation = provider.GetDocumentation(controllerDescriptor);
            if (documentation != null)
                return documentation;
        }
        return null;
    }

    public string GetResponseDocumentation(HttpActionDescriptor actionDescriptor)
    {
        foreach (XmlDocumentationProvider provider in xmlDocumentationProviders)
        {
            string documentation = provider.GetDocumentation(actionDescriptor);
            if (documentation != null)
                return documentation;
        }
        return null;
    }
}

This will be just wrapper over XmlDocumentationProvider - it will work with a collection of XmlDocumentationProvider and looks for the first one that will provide desired documentation. Then you change your configuration in HelpPageConfig to use your MultipleFilesXmlDocumentationProvider:

config.SetDocumentationProvider(
    new MultipleFilesXmlDocumentationProvider(
        new string[] { 
            HttpContext.Current.Server.MapPath("~/bin/WebAPI.XML"), 
            HttpContext.Current.Server.MapPath("~/bin/EntityModel.Definitions.XML")
        }
    )
 );

Of course take into account that for the configuration above both XML files should be within WebAPI project bin folder.

At

Just a note, this may possibly be due to a newer ASP.net but I also had to inherit from: IModelDocumentationProvider and implement: GetDocumentation(Type type) and GetDocumentation(MemberInfo member) – Reger