transporter_room_3
transporter_room_3

Reputation: 2633

Generate model description in AspNet WebApi help pages

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?

Upvotes: 6

Views: 4338

Answers (1)

Northstar
Northstar

Reputation: 343

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")));
    ......
}

Upvotes: 12

Related Questions