Creating the Help Page in ASP.NET Web API

Introduction

In this article we will define the process of creating the help page in the ASP .NET Web API. For creating the help page first we need to install the ASP .NET and Web Tools 2012.2 update. When we install this update it integrates the help page into the web API.

Step 1

We can install this update from this link: Click me

Step 2

We create the Web API application using the following:

• Start the Visual Studio 2012.
• Click on New Project and select the MVC4 application.
• Now select the Web API application from the template.

Step 3

Now we see the Areas folder in Solution Explorer. The Areas folder contains the help page folder.

Step 4

Now we execute the application.

When we execute the application we will see the API help page Link.

When we click on API help Link then open a API summary page.

Step 5

There are more links that are connected to the detailed information page. We will see this image for the Response body format.

Step 6

Adding the API Documentation

For adding the API Documentation go to Areas/HelpPage/App_Start/HelpPageConfig.cs and uncomment the following code in this file.

config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml")));

Step 7

Now we enable the XML Documentation. In the Solution Explorer right-click on the project and select the properties.

Then open this page.

In this window we select the Output and check the XML documentation file and in the edit box we type the following line in App_Data/XMLDocument.xml.

Step 8

Now we open the Valuescontroller API controller and add the some documentation comment For example:

using System;

using System.Collections.Generic;

using System.Linq;

using System.Net;

using System.Net.Http;

using System.Web.Http;

 

namespace MvcApplication4.Controllers

{

    public class ValuesController : ApiController

    {

        /// <summary>

        ///Fetch some important data from the server.

        /// </summary>

        public IEnumerable<string> Get()

        {

            return new string[] { "value1", "value2" };

        }

 

        /// <summary>

        /// Take Data by ID.

        /// </summary>

        /// <param name="id">The ID of the data.</param>

        public string Get(int id)

        {

            return "value";

        }

Step 9

Now we again run the application and we see that the documentation string is shown in the API table.

We can modify the layout of the API application such as Title, font size, color etcetera. Here we see an example of modifying the formatting of the API.

Here is an Index.cshtml file. For modifying the layout we perform the change in this file. This file exists in the Solution Explorer Areas/HelpPage/Views/Help/Index.cshtml.

@using System.Web.Http

@using System.Web.Http.Description

@using System.Collections.ObjectModel

@using MvcApplication4.Areas.HelpPage.Models

@model Collection<ApiDescription>

 

@{

    ViewBag.Title = "This is ASP.NET Web API Help Page";

 

    // Group APIs by controller

    ILookup<string, ApiDescription> apiGroups = Model.ToLookup(api => api.ActionDescriptor.ControllerDescriptor.ControllerName);

}

 

<header>

    <div class="content-wrapper">

        <div class="float-left">

            <h1>@ViewBag.Title</h1>

        </div>

    </div>

</header>

<div id="body">

    <section class="featured">

        <div class="content-wrapper">

         

            <h2>  <font color="Blue">Introduction</font></h2>

            <p>

                <font color="Red" size="20pt">

                Provide a general description of your APIs here.

                    </font>

            </p>

        </div>

    </section>

    <section class="content-wrapper main-content clear-fix">

        @foreach (var group in apiGroups)

        {

            @Html.DisplayFor(m => group, "ApiGroup")

        }

    </section>

</div>

 

@section Scripts {

    <link type="text/css" href="~/Areas/HelpPage/HelpPage.css" rel="stylesheet" />

}

 

Now it can look like this: