Web Api Help Pages

Setup

Note: When setting up Web Api Help Pages, make sure to enable it in your app, else the description field will not work.

• Go to Areas\HelpPage\App_Start\HelpPageConfig.cs. Around line 36, you’ll want to make sure you uncommented the line as below:

            //// Uncomment the following to use the documentation from XML documentation file.
            config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/ApiDocumentation.XML")));

• Go to Project=>Properties=>Build. Under Output, make sure the “XML documentation file” box is checked, and point it to App_Data\ApiDocumentation.XML
• Make sure to include the App_Data\ApiDocumentation.XML in the project and set it to “Copy always” for Copy to Output Directory. If you don’t do this, you will get the following message after deployment…

[DirectoryNotFoundException: Could not find a part of the path 'D:\home\site\wwwroot\App_Data\ApiDocumentation.XML'.]

Add Documentation

/// <summary>
/// Gets some very important data from the server.
/// </summary>
public IEnumerable<string> Get()
{
    return new string[] { "value1", "value2" };
}

/// <summary>
/// Looks up some data by ID.
/// </summary>
/// <param name="id">The ID of the data.</param>
public string Get(int id)
{
    return "value";
}

Under the Hood

The help pages are built on top of the ApiExplorer class, which is part of the Web API framework. The ApiExplorer class provides the raw material for creating a help page. For each API, ApiExplorer contains an ApiDescription that describes the API. For this purpose, an “API” is defined as the combination of HTTP method and relative URI. For example, here are some distinct APIs:

• GET /api/Products
• GET /api/Products/{id}
• POST /api/Products

If a controller action supports multiple HTTP methods, the ApiExplorer treats each method as a distinct API.

To hide an API from the ApiExplorer, add the ApiExplorerSettings attribute to the action and set IgnoreApi to true.C#Copy

[ApiExplorerSettings(IgnoreApi=true)]
public HttpResponseMessage Get(int id) {  }

You can also add this attribute to the controller, to exclude the entire controller.

The ApiExplorer class gets documentation strings from the IDocumentationProvider interface. As you saw earlier, the Help Pages library provides an IDocumentationProvider that gets documentation from XML documentation strings. The code is located in /Areas/HelpPage/XmlDocumentationProvider.cs. You can get documentation from another source by writing your own IDocumentationProvider. To wire it up, call the SetDocumentationProvider extension method, defined in HelpPageConfigurationExtensions

ApiExplorer automatically calls into the IDocumentationProvider interface to get documentation strings for each API. It stores them in the Documentation property of the ApiDescription and ApiParameterDescription objects.

Sources:

https://docs.microsoft.com/en-us/aspnet/web-api/overview/getting-started-with-aspnet-web-api/creating-api-help-pages

https://stackoverflow.com/questions/37458716/web-api-help-pages-not-loading-documentation-xml