Generate model description in AspNet WebApi help pages

Question

How do I generate a description for my model in Asp.Net Web Api help pages?

Example:

As you can see from the example, I can already generate Name, Type and Additional Information. But how do I generate Description?

I've tried nothing and I'm all out of ideas.

No, that's not true. I've tried adding comments to my TransactionDto class, but it does not work.

/// <summary>
/// A DTO (Data Transfer Object) for Transaction objects.
/// </summary>
public class TransactionDto
{
    /// <summary>
    /// The manager who registered the transaction.
    /// </summary>
    public string FromId { get; set; }

    /// <summary>
    /// The receiving manager.
    /// </summary>
    [Required]
    public string ToId { get; set; }

    /// <summary>
    /// Optional expiration date.
    /// </summary>
    public DateTime? Expires { get; set; }

    /// <summary>
    /// Date the transaction was created.
    /// </summary>
    public DateTime Created { get; set; }
}

I have configured HelpPageConfig.cs to use an XmlDocumentationProvider like so:

config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml")));

So how do I generate these descriptions for models?

Answer 1

I believe you have models in the separate project other than the Web API project?

If that is the case, the web API project is not aware of the help XML file generated for the models. you need to set the XML output path for both web API project and the models project and then combine both XML files in the register method of HelpPageConfig.cs file.

public static void Register(HttpConfiguration config)
{
        XmlDocument apiDoc = new XmlDocument();
        apiDoc.Load(HttpContext.Current.Server.MapPath("~/App_Data/WebApi.Orders.xml"));
        XmlDocument contractsDoc = new XmlDocument();
        contractsDoc.Load(HttpContext.Current.Server.MapPath("~/App_Data/Contracts.xml"));
        if (contractsDoc.DocumentElement != null && apiDoc.DocumentElement!=null)
        {
            XmlNodeList nodes = contractsDoc.DocumentElement.ChildNodes;
            foreach (XmlNode node in nodes)
            {
                XmlNode copiedNode = apiDoc.ImportNode(node, true);
                apiDoc.DocumentElement.AppendChild(copiedNode);
            }
            apiDoc.Save(HttpContext.Current.Server.MapPath("~/App_Data/WebApi.Orders.xml"));
        }
        config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/WebApi.Orders.xml")));
    ......
}