Generate model description in AspNet WebApi help pages

 

Questions


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

Example:

enter image description here

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

I think you have models in separate project other than the Web api project?

If that is the case, 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 webapi project and the models project and then combine the 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/VonExpy.AD.WebApi.Orders.xml"));
        XmlDocument contractsDoc = new XmlDocument();
        contractsDoc.Load(HttpContext.Current.Server.MapPath("~/App_Data/VonExpy.AD.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/VonExpy.AD.WebApi.Orders.xml"));
        }
        config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/VonExpy.AD.WebApi.Orders.xml")));
    ......
}

asp.net,asp.net-web-api,c#

Facebook Comments

Post a comment