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.
Step 2: Modifying the XmlDocumentationProvider
Next, we’re going to define a new interface called IResponseDocumentationProvider.
After that, we’ll have the XmlDocumentationProvider implement the IResponseDocumentationProvider to read the value in the <retuns> tag.
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.
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.
And that’s it, your help page now supports XML comment’s <returns> tag!
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.
Step 2: Creating the template view
Next, we’ll create a view named VideoSample.cshtml under the DisplayTemplates folder.
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.
That’s it, now you can use videos as samples!