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

  • Article

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: https://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 https://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

  • Anonymous
    April 10, 2013
    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.

  • Anonymous
    April 11, 2013
    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

  • Anonymous
    June 24, 2013
    Are there any plans to include support for self-hosted projects from the Web Api Help Page nuget package? Thanks.

  • Anonymous
    April 11, 2014
    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?  

  • Anonymous
    May 07, 2014
    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

  • Anonymous
    January 06, 2015
    Was there any progress made in this field to be part of main-stream self-hosted Web API package?

  • Anonymous
    June 08, 2015
    I second Greg's question.. are there any more updated/streamlined approaches to this?

  • Anonymous
    June 15, 2015
    what is the correct path to helpPage.css - at the moment it's unstyled?

  • Anonymous
    January 13, 2016
    The comment has been removed