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(newXmlDocumentationProvider(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
{
publicclassValuesController : ApiController
{
///<summary>
///Fetch some important data from the server.
///</summary>
publicIEnumerable<string> Get()
{
returnnewstring[] { "value1", "value2" };
}
///<summary>
/// Take Data by ID.
///</summary>
///<param name="id">The ID of the data.</param>
publicstring 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>
<divclass="content-wrapper">
<divclass="float-left">
<h1>@ViewBag.Title</h1>
</div>
</div>
</header>
<divid="body">
<sectionclass="featured">
<divclass="content-wrapper">
<h2> <fontcolor="Blue">Introduction</font></h2>
<p>
<fontcolor="Red"size="20pt">
Provide a general description of your APIs here.
</font>
</p>
</div>
</section>
<sectionclass="content-wrapper main-content clear-fix">
@foreach (var group in apiGroups)
{
@Html.DisplayFor(m => group, "ApiGroup")
}
</section>
</div>
@section Scripts {
<linktype="text/css"href="~/Areas/HelpPage/HelpPage.css"rel="stylesheet"/>
}
Now it can look like this:
