ASP.NET Web API Generate all parameters from model - help pages

Question

I\'m busy creating a Web API (Inside a asp mvc4 application). I am using the library suggested on the asp.net site for generating documentation (http://www.asp.net/web-api/overv

Answer 1

The MVC Web API documentation feature walks through your API classes and methods using reflection. This will build the structure of the documentation but will result in more or less empty (and useless) documentation unless you have added documentation comments.

The body of the documentation is filled using the XML file that is generated using /// documentation comments which has a specific structure that must be followed. That means that you can't fill your xml with whatever you want it to display, it actually has to be connected to something that is in your API and must follow the structure of your classes and properties.

So in your case you can't put model property documentation in an api method. You have to put it into the Model where the property exists.

MODEL:

  public class TestModel
  {
  /// 
This is the first name 
      property String FirstName {get;set;}
  /// 
This is the surname
      property String Surname {get; set;}
      property Boolean Active {get;set;} 
  }

ACTION:

  /// 

  /// This is a test action
  /// 
  /// this is the model 
  public HttpResponseMessage Post(my.namespace.models.TestModel model)
  {
    ...
  }

Modify Help Pages

The default Help pages that are automatically generated do not include Model documentation only the api methods are documented. In order to display more information about the parameters in your api a customisation is required. The instruction that follow are one way to add parameter documentation.

Create two new types in Areas/HelpPage/Models

public class TypeDocumentation
{
    public TypeDocumentation()
    {
        PropertyDocumentation = new Collection();
    }

    public string Summary { get; set; }
    public ICollection PropertyDocumentation { get; set; } 
}

public class PropertyDocumentation
{
    public PropertyDocumentation(string name, string type, string docs)
    {
        Name = name;
        Type = type;
        Documentation = docs;
    }
    public string Name { get; set; }
    public string Type { get; set; }
    public string Documentation { get; set; }
}

Add a new property to HelpPageApiModel.cs

public IDictionary ParameterModels{ get; set; } 

Create a new interface

internal interface IModelDocumentationProvider
{
    IDictionary GetModelDocumentation(HttpActionDescriptor actionDescriptor);
}

Modify XmlDocumentationProvider to implement the new interface

public class XmlDocumentationProvider : IDocumentationProvider, IModelDocumentationProvider
{
    private const string TypeExpression = "/doc/members/member[@name='T:{0}']";
    private const string PropertyExpression = "/doc/members/member[@name='P:{0}']";
///...
///... existing code
///...

    private static string GetPropertyName(PropertyInfo property)
    {
        string name = String.Format(CultureInfo.InvariantCulture, "{0}.{1}", property.DeclaringType.FullName, property.Name);
        return name;
    }

    public IDictionary GetModelDocumentation(HttpActionDescriptor actionDescriptor)
    {
        var retDictionary = new Dictionary();
        ReflectedHttpActionDescriptor reflectedActionDescriptor = actionDescriptor as ReflectedHttpActionDescriptor;
        if (reflectedActionDescriptor != null)
        {
            foreach (var parameterDescriptor in reflectedActionDescriptor.GetParameters())
            {
                if (!parameterDescriptor.ParameterType.IsValueType)
                {
                    TypeDocumentation typeDocs = new TypeDocumentation();


                    string selectExpression = String.Format(CultureInfo.InvariantCulture, TypeExpression, GetTypeName(parameterDescriptor.ParameterType));
                    var typeNode = _documentNavigator.SelectSingleNode(selectExpression);

                    if (typeNode != null)
                    {
                        XPathNavigator summaryNode;
                        summaryNode = typeNode.SelectSingleNode("summary");
                        if (summaryNode != null)
                            typeDocs.Summary = summaryNode.Value;
                    }

                    foreach (var prop in parameterDescriptor.ParameterType.GetProperties())
                    {
                        string propName = prop.Name;
                        string propDocs = string.Empty;
                        string propExpression = String.Format(CultureInfo.InvariantCulture, PropertyExpression, GetPropertyName(prop));
                        var propNode = _documentNavigator.SelectSingleNode(propExpression);
                        if (propNode != null)
                        {
                            XPathNavigator summaryNode;
                            summaryNode = propNode.SelectSingleNode("summary");
                            if (summaryNode != null) propDocs = summaryNode.Value;
                        }
                        typeDocs.PropertyDocumentation.Add(new PropertyDocumentation(propName, prop.PropertyType.Name, propDocs));

                    }
                    retDictionary.Add(parameterDescriptor.ParameterName, typeDocs);
                }

            }

        }

        return retDictionary;
    }
}

Add code to HelpPageConfigurationExtension in GenerateApiModel method

IModelDocumentationProvider modelProvider =
            config.Services.GetDocumentationProvider() as IModelDocumentationProvider;
if (modelProvider != null)
{
    apiModel.ParameterModels = modelProvider.GetModelDocumentation(apiDescription.ActionDescriptor);
}

Modify HelpPageApiModel.cshtml adding to following where you want the Model documentation to be displayed.

bool hasModels = Model.ParameterModels.Count > 0;
if (hasModels)
{
     
Parameter Information
  @Html.DisplayFor(apiModel => apiModel.ParameterModels, "Models")

}

Add a Models.cshtml to DisplayTemplates

@using System.Web.Http
@using System.Web.Http.Description
@using MvcApplication2.Areas.HelpPage.Models
@model IDictionary

@foreach (var modelType in Model)
{
    
@modelType.Key
    if (modelType.Value.Summary != null)
    {
    
@modelType.Value.Summary
    }
    
            @foreach (var propInfo in modelType.Value.PropertyDocumentation)
            {
                
            }
        

        

            

                
Property

                
Description
            
        
        

                    
@propInfo.Name (@propInfo.Type)

                    

                        
@propInfo.Documentation
                    
                
    
}