Deborah's Developer MindScape






         Tips and Techniques for Web and .NET developers.

September 28, 2012

Web API Help Page and XML Comments

Filed under: ASP.NET,ASP.NET Web API,C#,VB.NET @ 1:32 am

The virtues of a Web API Help Page were extolled in a prior post. That prior post demonstrated the "out of the box" functionality of the Microsoft ASP.NET Web API Help Page. This post extends that functionality to include the XML comments from your code.

You can adjust the configuration file for the Help Page to set the documentation provider to your code’s XML comments. That way your help file documentation will match the XML comments from your code.

Let’s work through an example:

[See this prior post for an introduction to building an ASP.NET Web API service. The service created in that post is the example service used here.]

[[NOTE: The ASP.NET Web API Help Page is in prerelease and does not currently work with VB.NET.]]

Here is the prior example Web API service with XML Comments added:

In C#:

using ACMService.Models;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Web.Http;

namespace ACMService.Controllers
{
    /// <summary>
    /// Provides customer information.
    /// </summary>
    public class CustomerController : ApiController
    {
        /// <summary>
        /// Provides information for the full list of customers.
        /// </summary>
        /// <returns></returns>
        /// <example>GET api/customer</example>
        public IEnumerable<Customer> Get()
        {
            return Customer.Retrieve();
        }

        /// <summary>
        /// Provides information for a single customer by Id.
        /// </summary>
        /// <param name="id">Customer Id</param>
        /// <returns></returns>
        /// <example>GET api/customer/2</example>
        public Customer Get(int id)
        {
            List<Customer> customerList = Customer.Retrieve();
            Customer customerInstance = customerList.FirstOrDefault(
                                    c => c.CustomerId == id);
            if (customerInstance == null)
            {
                throw new HttpResponseException(new HttpResponseMessage(HttpStatusCode.NotFound)
                    {
                        Content = new StringContent("Could not locate a customer with id: " + id),
                        ReasonPhrase = "Customer Id not found"
                    });
            }
            return customerInstance;
        }
    }
}

In VB:

Imports System.Net
Imports System.Net.Http
Imports System.Web.Http

”’ <summary>
”’ Privides customer information.
”’ </summary>
”’ <remarks></remarks>
Public Class CustomerVBController
    Inherits ApiController

    ”’ <summary>
    ”’ Provides information for the full list of customers.
    ”’ </summary>
    ”’ <returns></returns>
    ”’ <example>GET api/customerVB</example>
    Public Function [Get]() As IEnumerable(Of CustomerVB)
        Return CustomerVB.Retrieve()
    End Function

    ”’ <summary>
    ”’ Provides information for a single customer by Id.
    ”’ </summary>
    ”’ <param name="id">Customer Id</param>
    ”’ <returns></returns>
    ”’ <example>GET api/customerVB/2</example>
    Public Function [Get](id As Integer) As CustomerVB
        Dim customerList = CustomerVB.Retrieve()
        Dim customerInstance = customerList.FirstOrDefault(
                    Function(c) c.CustomerId = id)
        If customerInstance Is Nothing Then
            Throw New HttpResponseException(New HttpResponseMessage(HttpStatusCode.NotFound) With
            {
              .Content = New StringContent("Could not locate a customer with id: " & id),
                    .ReasonPhrase = "Customer Id not found"
            })
        End If
        Return customerInstance
    End Function
End Class

To modify the Help Pages to use the XML comments from the above code, follow these steps:

1) Ensure that your code has XML comments. (See the examples above.)

2) Modify the HelpPageConfig file.

Find it in Solution Explorer under your Web API project, Areas / HelpPage / App_Start folder.

3) Uncomment the code line provided in the HelpPageConfig file to set the documentation provider to the XML document generated from your Web API code.

image

4) Ensure that your build generates the required XML file.

image

5) Ensure that the XML file name used in the dialog above matches the XML file name defined in the HelpPageConfile file:

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

6) Execute the Web API project in Visual Studio and append "/help" to the address bar of the browser.

The result is shown below:

image

Notice that the description is now taken from your XML comments.

Drill down to see the detail:

image

Use these extra steps any time you want to use your Web API XML comments in your help pages.

Enjoy!

RSS feed for comments on this post. TrackBack URI

Leave a comment

© 2019 Deborah's Developer MindScape   Provided by WPMU DEV -The WordPress Experts   Hosted by Microsoft MVPs