WebApi Help Page Description

Question

What populates the Webapi method's description on the helper page and the introduction paragraph?

Yestreen

Answer 1

According to this article you can use XML documentation comments to create the documentation. To enable this feature, open the file Areas/HelpPage/App_Start/HelpPageConfig.cs and uncomment the following line:

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

Now enable XML documentation. In Solution Explorer, right-click the project and select Properties. Select the Build page.

Under Output, check XML documentation file. In the edit box, type “App_Data/XmlDocument.xml”.

Add some documentation comments to the controller methods. For example:

/// <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";
}

Opportune

For me (VS2013) there was something more to be done. 1.) The path of the documentation file under output had to be with a backslash, not normal slash. 2.) In the solution explorer, I had to add the XmlDocument.xml to the project (toggle the 'view all' button first) and set the 'copy to output directory' property of the file to 'copy if newer' (see CodeNotFounds answer) – Thibodeau

Spot on. If you want to omit an ApiController from the help documentation there is this attribute out of box - [ApiExplorerSettings(IgnoreApi = true)]. – Markos

Answer 2

To view the description you need to follow this :

1. Every action in your Customer controller must have a XML documentation
2. Open the properties of the project that contains your controllers and enable XML documenation like this :

3. In the Register method for HelpPageConfig class ( Areas/HelpPage/App_Start/HelpPageConfig.cs) uncomment the line 19 and don't forget to change the file path like this :

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

This all you must do. Last thing is to include the file created in App_Data in your project so the file will be deployed in production.

Tetrahedron

Note that the XML file is built/updated automatically each time solution is rebuilt. The comments shown in nznoor's example are picked up automatically for the documentation comments and used as the DESCRIPTION – Lucarne

Answer 3

For those of you using VB.NET, you seem to have to do it a little differently.

You have to go to the "Compile" tab (there is no Build tab) for the Web API project, then ensure "Generate XML documentation file" checkbox is checked.

The output actually gets put in /bin/{projectName}.xml, so now you have to change the SetDocumentationProvider call to point to the path "~/bin/{projectname}.xml" (obviously, replace {projectname} with your actual project name).

This seems smelly, so please let me know if anybody finds a different way to do it.

Unanimity

This works for VB.net. When you build the App a file is generated with the project name in /bin/WebApplication.xml. I had to create a new file with the same name in the /App_Data/ folder and copy the contents from the bin file. – Straitlaced

Or change the SetDocumentationProvider path to the /bin/ folder config.SetDocumentationProvider(New XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/Bin/WebApplication.xml"))) – Straitlaced