How To Create Help Pages(Documents) For Asp.Net Web API

In this tutorial i am going to explain about how to create help pages to asp.net web api using Microsoft.AspNet.WebApi.HelpPage  package. Here i will explain how to add the help page for existing Web API as well as the new Web API Project that has to be created.


In my previous article i have explained about Store Custom Objects In Configuration File , Create Simple Mathmatical Captcha In ASP.Net , Visual Studio Keyboard Shortcuts , How To get data from WEB API , How To Create Your First WEB API Project, Check Container Exists In Azure Blob and many articles in C#.Net,VB.Net,Grid View,Javascript,jQuery,SQL Server and many other topics.

Whenever we create Web API it is very useful and must to create the help pages so that other developers who consumes /uses the web api for development will know for which purpose a particular web api is used. To make this task easier, ASP.NET Web API provides a library for auto-generating help pages at run time. Before proceeding to create WEB API helppages you suppose to install ASP.NET and Web Tools 2012.2 Update this update will integrate helppages into web api template.

Now please look into my previous article How To Create Your First WEB API Project to create the web api project. Now i will explain about how to add help pages to an existing web api project.

After creating your web api project go to Tools ==> NuGet Package Manager ==> Package Manager Console as shown in the below figure.

Now type the below command.
For C#.Net: Install-Package Microsoft.AspNet.WebApi.HelpPage
For VB.Net:Install-Package Microsoft.AspNet.WebApi.HelpPage.VB

This command will install all the necessary assemblies and MVC views to render helppage. After installing you can see a folder named Areas in your project. Inside the areas folder you can see controller for help and views like shown in below figure.

Now we have to register Areas. Open the Global.asax file and in the Application_Start method add the AreaRegistration.RegisterAllAreas() code. AreaRegistration class is available under System.Web.Mvc namespace. So you may need to include this namespace if it is not already there. The entire code is given below.

using System;

using System.Collections.Generic;

using System.Linq;

using System.Web;

using System.Web.Http;

using System.Web.Routing;

using System.Web.Mvc;

namespace ypapi

{

    public class WebApiApplication : System.Web.HttpApplication

    {

        protected void Application_Start()

        {

            GlobalConfiguration.Configure(WebApiConfig.Register);

           

            // Add this code, if not present.

            AreaRegistration.RegisterAllAreas();

        }

    }

}

Now if you run the application the relative URI for the helppage is /Help. Below is the sample output.

By default the help page will have placeholder text for documentation.You can use XML Documentation comments for to create the documentation. For this open the file Areas/HelpPage/App_Start/HelpPageConfig.cs and uncomment the following line.

//// Uncomment the following to use the documentation from XML documentation file.

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

And then right click the project in solution explorer then select Properties then Build page like below.Under Output, check XML documentation file and In the edit box, type "App_Data/XmlDocument.xml".

Now open your controller (Any Controller not the help controller) and add the xml comment to each action and also you can add xml comment for the controller too like below.

using System;

using System.Collections.Generic;

using System.Linq;

using System.Net;

using System.Net.Http;

using System.Web.Http;

using WebApiDemo.Models;

// Add this code, if not present.

using System.Web.Http.Description;

namespace WebApiDemo.Controllers

{

    /// <summary>

    /// It has the APIs related to employees

    /// </summary>

    public class EmployeeController : ApiController

    {

        Employee[] employees = new Employee[]

        {

            new Employee { EmployeeId = 1, EmployeeName = "Kannadasan", Department = "Development", Designation = "Development Lead" },

            new Employee { EmployeeId = 2, EmployeeName = "Kaviyarasan", Department = "Quality Control", Designation = "Quality Lead" },

            new Employee { EmployeeId = 3, EmployeeName = "Xavier", Department = "Development", Designation = "Tech Lead" },

            new Employee { EmployeeId = 4, EmployeeName = "Ramkumar", Department = "Design", Designation = "Design Lead" }

        };

        /// <summary>

        /// Returns list of all the employees

        /// </summary>

        /// <returns></returns>

       

        public IEnumerable<Employee> GetAllEmployees()

        {

            return employees;

        }

        /// <summary>

        /// Returns the specific employee record

        /// based on the employee id

        /// </summary>

        /// <param name="id">EmployeeId</param>

        /// <returns></returns>

        public IHttpActionResult GetEmployee(int id)

        {

            var employee = employees.FirstOrDefault((p) => p.EmployeeId == id);

            if (employee == null)

            {

                return NotFound();

            }

            return Ok(employee);

        }

    }

}

Now if you run the application you will see the api with description grouped by each controller. If you click on each API it will provide the detailed documentation of API properties and sample json and xml outputs like below.

You can exclude a particular API or even a Controller if you don't want to add it in the Web API help page by using ApiExplorerSettings(IgnoreApi=true) attribute (ApiExplorerSettings is available in the System.Web.Http.Description namespace. You suppose to include it in the page). The sample code is given below

[ApiExplorerSettings(IgnoreApi = true)]

public IEnumerable<Employee> GetAllEmployees()

{

    return employees;

}

After excluding the API the output will be as shown in figure

SourceCode:

If you like this article then share with your friends and comment your valuable feedback.. Happy coding..

You May Also Like...

• How To Create Help Pages(Documents) For Asp.Net Web API
• How to get/fetch data from ASP.Net WebAPI or how to query ASP.Net WebAPI.
• How to create your first WEB API Project in ASP.Net MVC