ASP.NET Web API Help Page Part 3: Advanced Help Page customizations

In this post, I’ll go over some advanced customization scenarios for ASP.NET Web API Help Page. First, I’ll demonstrate how you can enable new functionalities such as displaying the documentation in the <returns> tag by adding a new property to the HelpPageApiModel. Second, I’ll show you how to create a custom display template for samples that aren’t texts or images but videos. With that in mind, let’s get started.

1. Adding additional information to the HelpPageApiModel

Note that in this post I’ll only add the support for the documentation in the <returns> tag, but you can use the same pattern for the documentation in other XML comment tags.

Step 1: Adding a ResponseDocumentation property to the HelpPageApiModel

We are going to start by adding a new property to the HelpPageApiModel so that we can store the comments from the <returns> tag.

 public class HelpPageApiModel
 {
     public string ResponseDocumentation { get; set; }
  
     // existing code
 }

Step 2: Modifying the XmlDocumentationProvider

Next, we’re going to define a new interface called IResponseDocumentationProvider.

 public interface IResponseDocumentationProvider
 {
     string GetResponseDocumentation(HttpActionDescriptor actionDescriptor);
 }

After that, we’ll have the XmlDocumentationProvider implement the IResponseDocumentationProvider to read the value in the <retuns> tag.

 public virtual string GetResponseDocumentation(HttpActionDescriptor actionDescriptor)
 {
     XPathNavigator methodNode = GetMethodNode(actionDescriptor);
     if (methodNode != null)
     {
         XPathNavigator returnsNode = methodNode.SelectSingleNode("returns");
         if (returnsNode != null)
         {
             return returnsNode.Value.Trim();
         }
     }
  
     return null;
 }

Step 3: Populating the ResponseDocumentation

In HelpPageConfigurationExtensions.cs, we’re going to add some logic that will get back the XmlDocumentationProvider as IResponseDocumentationProvider and populate the ResponseDocumentation with the value in the <returns> tag.

 private static HelpPageApiModel GenerateApiModel(ApiDescription apiDescription, HelpPageSampleGenerator sampleGenerator, HttpConfiguration config)
 {
     HelpPageApiModel apiModel = new HelpPageApiModel();
     apiModel.ApiDescription = apiDescription;
  
     IResponseDocumentationProvider responseDocProvider = config.Services.GetDocumentationProvider() as IResponseDocumentationProvider;
     if (responseDocProvider != null)
     {
         apiModel.ResponseDocumentation = responseDocProvider.GetResponseDocumentation(apiDescription.ActionDescriptor);
     }
     
     // existing code
 }

Step 4: Displaying ResponseDocumentation on the View

As the latest step, we’re going to add something to the HelpPageApiModel.cshtml to display the ResponseDocumentation.

 @if (hasResponseSamples)
 {      
     <h2>Response Information</h2> 
     if (!String.IsNullOrEmpty(Model.ResponseDocumentation))
     {
         <p>@Model.ResponseDocumentation</p>
     }
     <h3>Response body formats</h3>
     @Html.DisplayFor(apiModel => apiModel.SampleResponses, "Samples", new { sampleClass = "response" })
 }

Result

And that’s it, your help page now supports XML comment’s <returns> tag!

image image

 

2. Creating new sample display templates

You can easily create reusable samples that aren’t text based using display templates. For illustration, I’ll create a new template to display video samples for APIs that return video/mp4 as the content type.

Step 1: Creating the template model

First, we start by creating a VideoSample class which we’ll use to represent a video sample.

 public class VideoSample
 {
     public VideoSample(string src)
     {
         if (src == null)
         {
             throw new ArgumentNullException("src");
         }
         Src = src;
     }
  
     public string Src { get; private set; }
 }

Step 2: Creating the template view

Next, we’ll create a view named VideoSample.cshtml under the DisplayTemplates folder.

image

 @model VideoSample
  
 <video width="320" height="240" controls="controls">
   <source src="@Model.Src" type="video/mp4">
   <object data="@Model.Src" width="320" height="240">
   </object>
 </video>

Step 3: Setting the sample

Now all we need to do is to set the sample on the API that returns video/mp4. For instance, you can use SetSampleResponse to set the response sample.

 public static class HelpPageConfig
 {
     public static void Register(HttpConfiguration config)
     {
         config.SetSampleResponse(new VideoSample("/Videos/movie.mp4"), new MediaTypeHeaderValue("video/mp4"), "Values", "Post");
     }
 }

Result

That’s it, now you can use videos as samples!

image

 

Related blog posts

ASP.NET Web API Help Page Part 1: Basic Help Page customizations

ASP.NET Web API Help Page Part 2: Providing custom samples on the Help Page