Making ASP.NET Web API Help Page work on self-hosted services


Even though ASP.NET Web API Help Page is implemented using ASP.NET MVC, which won’t work on self-hosted services, most of the code in the package however can be reused to support the generation of Help Page on self host. I’ve created a sample to illustrate how this can be done. The code can be downloaded at: http://code.msdn.microsoft.com/ASPNET-Web-API-Help-Page-40e1a68e.

The idea is simple, replace MVC components with Web API. So instead of implementing the HelpController as a MVC Controller, implement it as an ApiController. For the rendering of HTML, I used T4 in the sample, but you’re free to use any templating engine you like. Now let’s look at the sample.

Web Api Help Page Self Host Sample

The sample contains two projects: WebApiHelpPageSelfHost.csproj and SampleWebApiSelfHost.csproj. To run the sample, make sure you Enable NuGet Package Restore. (Inside VS, go to Tools -> Options… -> Package Manager -> check "Allow NuGet to download missing packages during build" option)

WebApiHelpPageSelfHost.csproj

This project contains the source code for the Help Page. All the files come from the ASP.NET Web API Help Page package, except for the HelpControllerBase.cs and the files under the Views folder.

The HelpControllerBase is a ApiController as noted previously and it has two actions that will return the help page in “text/html” format.

[ApiExplorerSettings(IgnoreApi = true)]
public abstract class HelpControllerBase : ApiController
{
    public string HelpPageRouteName = "Default";
 
    [HttpGet]
    public virtual HttpResponseMessage Index()
    {
        Index template = new Index
        {
            Model = Configuration.Services.GetApiExplorer().ApiDescriptions,
            ApiLinkFactory = apiName =>
            {
                string controllerName = Regex.Replace(GetType().Name, "controller", "", RegexOptions.IgnoreCase);
                return Url.Route(HelpPageRouteName, new { controller = controllerName, apiId = apiName });
            }
        };
        string helpPage = template.TransformText();
        return new HttpResponseMessage
        {
            Content = new StringContent(helpPage, Encoding.UTF8, "text/html")
        };
    }
 
    [HttpGet]
    public virtual HttpResponseMessage Api(string apiId)
    {
        if (!String.IsNullOrEmpty(apiId))
        {
            HelpPageApiModel apiModel = Configuration.GetHelpPageApiModel(apiId);
            if (apiModel != null)
            {
                string controllerName = Regex.Replace(GetType().Name, "controller", "", RegexOptions.IgnoreCase);
                Api template = new Api
                {
                    Model = apiModel,
                    HomePageLink = Url.Link(HelpPageRouteName, new { controller = controllerName })
                };
                string helpPage = template.TransformText();
                return new HttpResponseMessage
                {
                    Content = new StringContent(helpPage, Encoding.UTF8, "text/html")
                };
            }
        }
 
        return Request.CreateErrorResponse(HttpStatusCode.NotFound, "API not found.");
    }
}

The files under the Views folder are T4 templates used to render the HTML. I used partial classes (Index and Api) to pass the data to the templates.

partial class Index
{
    public Collection<ApiDescription> Model { get; set; }
 
    public Func<string, string> ApiLinkFactory { get; set; }
}
 
partial class Api
{
    public HelpPageApiModel Model { get; set; }
 
    public string HomePageLink { get; set; }
}

SampleWebApiSelfHost.csproj

This project contains a self-hosted Web API service with the help page enabled. It references the WebApiHelpPageSelfHost.csproj. You can simply build and run this project to see the self-hosted Help Page in action.

image

Open a browser and go to http://localhost:8080/help to see the following pages.

image

image

Note that the HelpControllerBase from WebApiHelpPageSelfHost.csproj is an abstract class so it won’t be added to your service unless you derive from it.

// Change the controller name if you want a different URI.
public class HelpController : HelpControllerBase { }

 

Have fun playing with the sample!

Yao

Comments (9)

  1. Billy C says:

    I installed the Api Help Package. Now everytime I create a MVC Web Api project, I get and Areas folder with a HelpPage area under. How do I make Visual Studio stop doing that? I do not want a HelpPage area in all my Web Api projects I create.

  2. Hi Billy,

    Did you install the ASP.NET and Web Tools 2012.2 update? The help page is added by default as part of the Web API template after the update. As part of the roadmap for the next version, we're looking at improving the project template creation experience in general: channel9.msdn.com/…/DEV301 For now, you can just uninstall the help package is you don't need it.

    Thanks,

    Yao

  3. Justin says:

    Are there any plans to include support for self-hosted projects from the Web Api Help Page nuget package?

    Thanks.

  4. Mike says:

    Is there a way of taking the document.xml file from the self-hosted webapi project and use it for documentation running on a different solution?  

  5. xihita says:

    Hi Yao,

    I'm creating an app that as to present a web page with charts.

    I have created a service that collects the info that's necessary and change it to make it a web api self-host.

    My problem is that now i want to create the 'client' and i have converted a previously created web page with the layout that i want but now i can't load my css and js files, when i'm inspecting the element it tells me that the files (css and js) are not found, although i've insert them in my client project.

    I already use include file but it won't show all the css code.

    Can you give some help?

    Thk

  6. Greg says:

    Was there any progress made in this field to be part of main-stream self-hosted Web API package?

  7. Anonymous says:

    I second Greg's question.. are there any more updated/streamlined approaches to this?

  8. Anonymous says:

    what is the correct path to helpPage.css – at the moment it's unstyled?

  9. DalSoft says:

    Hi Yao,

    I hope you don't mind but I extended your idea to work as Owin middleware so that it uses Razor templates and works on self-host. What do you think?

    http://www.dalsoft.co.uk/…/introducing-dalsoft-webapi-helppage-help-pages-for-asp-net-web-api-working-on-owin-self-host