ASP.NET Web API 2: Beginner Guide (2015)

Help Page Generation from XML Documentation

By default, Web API provides help pages related to the API methods defined in the project. We can generate the help pages from the XML documentations provided as part of the method definition.

To create the help pages, expand the Areas node in Solution Explorer and then open the HelpPageConfig.cs file

Figure 12: Accessing the HelpPageConfig.cs file in the sample Web API project

In the HelpPageConfig.cs file, un-comment the following statement:

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

Next, enable XML documentation by selecting the XML documentation file option in the Build section of the project’s properties, as shown in Figure 11. Copy the filename specified in the config file to the XML documentation file option.

Figure 13: Enabling the XML documentation file in the Web API project

Now, let’s add the XML documentation to our sample API controller, as shown in Listing 9. Just before each method definition, specify “///” to get the default XML documentation for the method. Modify further with more specific comments.

/// <summary>

/// Get All products for our Sample

/// </summary>

/// <returns></returns>

public IEnumerable<Product> GetAllProducts()

{

---------------

}

/// <summary>

/// Return the details of selected product depends on the product id passed.

/// </summary>

/// <param name="selectedId"></param>

/// <param name="name"></param>

/// <returns></returns>

public IEnumerable<Product> GetProducts(int selectedId)

{

------------------

}

Listing 9: Adding XML documentation to the sample API controller

Once you’ve updated the controller, run the application and navigate to API link at the top-right corner of the browser screen, as shown in next Figure.

Figure 14: Viewing the API link in the application window

Click the API link to open the help page. Notice the XML documentation comments that had been added to the controller, as shown in next Figure.

Figure 15: Viewing the comments in the Web API help file