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


Now that you have installed the ASP.NET Web API Help Page, I’m going to walk you through some of the basic customizations that you can do to make the help page more personalized.

Changing the help page URI

By default, the help page is available at /help. However you can easily change that in the HelpPageAreaRegistration.cs.

image

In the RegisterArea method, you can change the help page route URI to whatever you want. For example, the following will make the help page available at /document instead.

image

 

Providing API documentations

The help page package comes with an XmlDocumentationProvider which allows you to document your APIs using xml comments.

image

The ideal place to wire up the XmlDocumentationProvider is in HelpPageConfig.cs. The XmlDocumentationProvider constructor would take a physical path to your xml documentation file.

image

// Uncomment the following to use the documentation from XML documentation file.
config.SetDocumentationProvider(new XmlDocumentationProvider("physical path to your xml documentation"));

Once that’s done you should see the comments showing up on the help page.

image

 

Customizing the view

Changing the layout

You can change the look and feel of the help page using Razor layouts. This allows help page to inherit the look and feel of your existing sites.

First, make sure that your layout page have the following:

@RenderBody()
@RenderSection("scripts", required: false)

Then, open _ViewStart.cshtml and change the Layout path to your layout page.

image

For example the following will use the layout page under “Views/Shared” instead of “Areas/HelpPage/Views/Shared”.

@{
    // Change the Layout path below to blend the look and feel of the help page with your existing web pages.
    Layout = "~/Views/Shared/_Layout.cshtml";
}

image

Editing the CSHTMLs

The help page is mainly composed by two pages: Index.cshtml (lists all APIs) and Api.cshtml (describes one API). Each of these displays the model using DisplayTemplates and you can edit any of the cshtml files.

image

The following is a mapping of the cshtml files to the corresponding view in HTML.

Index.cshtml image
Api.cshtml image
ApiGroup.cshtml image
HelpPageApiModel.cshtml image
ImageSample.cshtml image
InvalidSample.cshtml image
Parameters.cshtml image
Samples.cshtml image
TextSample.cshtml image

 

Related blog posts

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

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

Comments (22)

  1. Rahul says:

    I am taking an object as input parameter such as

    public string GetData([FromUri]Product product)

    {

               //…..

    }

    But while generating the help page i want to include the properties of product class. Is it possible??

  2. PatrickSully says:

    How do I get the tabs on the Samples area?

  3. PatrickSully says:

    I am talking about the actual display you have on your side for Samples.cshtml

  4. @PatrickSully

    It was using JQuery UI.

    $(function () {

              $('.mediaTypeTabs').tabs();

    });

  5. Ahsan says:

    Hi Yao,

    First of all, I would like to thank you for sharing such a good tutorial. I have one question. In my scenario, I have the service in a self hosted manner. How can I configure help in my case? Thanks in anticipation!

  6. @Ahsan

    Currently, the Help Page package is implemented for web host only and you'll have to modify it to work on the self host. Basically you'll need to generate the HTML without using MVC, so instead of implementing the HelpController as a MVC Controller, you implement it as another ApiController. In that Help ApiController, you can use any templating engine you like (T4, RazorEngine, etc) to generate the documentation in HTML format and return it as an HttpResponseMessage.

    Hope this helps,

    Yao

  7. Dave says:

    Hi Yao,

    thanks for sharing this great tutorial, I have read the comments I noticed it's not so simple for a Web Apo self host application, you'd mentioned that you will blog about that later, in the first series. Are you still going to blog about that? I hope so.

    But most of all thanks for sharing !!

    Greetings,

    Dave

  8. Adrian says:

    How do you get it so that it documents APIs that are located in Areas?

  9. Hi Adrian,

    Web API doesn't provide out of box support for Areas at the moment.

    Thanks,

    Yao

  10. Erin says:

    Is there a way to make it so that the Help page provides the return values for the methods also?

  11. Hi xiaobao,

    For Q1 and Q2, part 2 of this series might help: blogs.msdn.com/…/asp-net-web-api-help-page-part-2-providing-custom-samples-on-the-help-page.aspx

    For Q3, can you not use XML comments like below to describe the complex parameter?

           /// <summary>

           /// Posts the specified value.

           /// </summary>

           /// <param name="value">

           /// PropertyA – optional.

           /// PropertyB – required.

           /// </param>

           public void Post(ComplexType value)

           {

           }

  12. Hi Erin,

    Do you mean providing documentation for the return value? If so, take a look at my other post: blogs.msdn.com/…/asp-net-web-api-help-page-part-3-advanced-help-page-customizations.aspx

  13. Gudjon says:

    How do I make Help Pages my default home page?

  14. Marcusdev says:

    Does it support the same info from odataControllers?

  15. Nilesh Ahir says:

    Hi Yah,

    How can I put the following jQuery code?

    $(function () {

             $('.mediaTypeTabs').tabs();

    });

    I have put it on sample.vbhtml, but it doesn't work.

    Thanks

  16. JAGAN says:

    Hi i have one question in Web Api Documentation. It Return the response or request value three items. For it should return values for only one time

  17. daksh says:

    how can we use documentation  in  web api 2.  i mean i download the help page and run it but i cant access

  18. Api Explorer is awesome but I have found 1 issue says:

    My controller function return Task<HttpResponseMessage> so when I try to pick up customizations by adding the line

    config.SetActualResponseType(typeof(IAccount), "Account", "GetDDAAccount");

    it doesn't work, is this because it returns type Task<HttpResponseMessage> instead of just HttpResponseMessage?