WebApi Help Page: don't escape HTML in XML documentation

Question

I am using XML Documentation for my ASP.NET Web API Help Page as shown here. I would like to know if there is a way to include html in the comments such that it will be rendered on the web page, instead of it being removed/ignored/escaped.
Specifically, I am looking for a way to create a newline, but being able to create bulleted lists, etc. would be great!

Ex/ I would like to be able to do something like this:

/// <summary>
/// CRUD operations for SalesDocument<br/>
/// This is a new line
/// </summary>
[RoutePrefix("api/SalesDocument")]
public partial class SalesDocumentController : ApiController

And have it show on the help page like this:

CRUD operations for SalesDocument 
This is a new line.

Instead of this: (in this case, <br/> gets removed somehow - if I try using <p> tags, they are just escaped)

CRUD operations for SalesDocument This is a new line.

*I have already tried the <para> tag as suggested by multiple posts for tooltips, but this does not work on my help page.

Any suggestions are greatly appreciated!

score 35 · Accepted Answer · edited Feb 04 '19 at 16:13

35

In the installed XmlDocumentationProvider.cs file at Areas\HelpPage, you can look for a method called GetTagValue. Here modify the return value from node.Value.Trim() to node.InnerXml.

private static string GetTagValue(XPathNavigator parentNode, string tagName)
{
    if (parentNode != null)
    {
        XPathNavigator node = parentNode.SelectSingleNode(tagName);
        if (node != null)
        {
            return node.InnerXml; 
        } 
    }

    return null;
}

Now open the installed file Areas\HelpPage\Views\Help\DisplayTemplates\ApiGroup.cshtml and modify the following line from:

<p>@controllerDocumentation</p>

to

<p>@Html.Raw(controllerDocumentation)</p>

edited Feb 04 '19 at 16:13

bluish

26,356
27
122
180

answered Mar 12 '14 at 16:15

Kiran

56,921
15
176
161

Fantastic! The `@Html.Raw` was the key I was missing... 1000 thanks to you good sir, you just made my day! =) – sǝɯɐſ Mar 12 '14 at 18:55
16

I was wondering why it wasn't working for me, then I realized it needs to be done in multiple places (depending on where you want tags to work). The ones I did were ApiGroup.cshtml, HelpPageApiModel.cshtml and ResourceModel.cshtml (look for .Documentation and .RequestDocumentation in each). Thought it might help the next person that finds this :) – zeroid May 09 '14 at 13:08
4

I had to change `return parameterNode.InnerXml;` in `GetDocumentation` to work with the parameter sections – Christopher G. Lewis Jan 06 '15 at 23:02
5

Do you think this would be worth making pull requests for the HelpPages project on GitHub? – devlord Apr 02 '15 at 18:32
2

Instead of writing html code in the comments it is proposed to just do a find and replace for new lines: http://stackoverflow.com/a/25464271/632495 – Jon49 Feb 24 '16 at 17:37
Didn't help me. Has that way become useless? – Yeheshuah Nov 22 '19 at 07:46

score 2 · Answer 2 · edited May 29 '17 at 11:43

2

@controllerDocumentation does not work for me, but changing the line to@api.Documentation works. i.e. @html.raw(api.Documentation).

edited May 29 '17 at 11:43

user1438038

5,821
6
60
94

answered May 29 '17 at 10:02

Michael

21
1

WebApi Help Page: don't escape HTML in XML documentation

2 Answers2

Linked