带有 markdown 注释的 ASP.NET Web API 帮助页面答案

【问题标题】：ASP.NET Web API Help Page with markdown comments带有 markdown 注释的 ASP.NET Web API 帮助页面
【发布时间】：2018-12-22 23:32:39
【问题描述】：

我使用asp.net WebApi Help Page 从源代码的 cmets 生成文档。并且我之前使用过doxygen 来生成文档。 doxygen 可以解析 cmets 中的 markdown 语法并输出格式良好的文档。但是WebApi Help Page 现在无法解析 markdown 语法。

例如foo函数的cmets包含Markdown cmets，在WebApi Help Page中会输出为### Markdown comments *It will return "foo" *It always returns "foo"。

public MyApiController : ApiController {
     ///<summary>
     /// It will return "foo"
     /// ### Markdown comments
     /// * It will return "foo"
     /// * It always returns "foo"
     ///</summary>    
     [HttpPost, ActionName("foo")]
     public string Foo() {
         return "foo";
     }
}

【问题讨论】：

我不知道'doxygen'，但你可以编写自己的IDocumentationProvider 实现并将其提供给HelpPage，或者你可以查看已安装的HelpPage 文件Areas\HelpPage\XmlDocumentationProvider.cs 并修改它根据您的需要
我读过IDocumentationProvider@MSDN，它返回“字符串”。但是MarkdownDeep 将string 作为输入并将其转换为IHtmlString。
现在，我修改了Area\HelpPage\Views\DisplayTemplates，并将document字符串转换为`@Html.Markdown(document)。

标签： c# asp.net asp.net-web-api asp.net-web-api-helppages markdowndeep

【解决方案1】：

感谢提示，刚刚修改HelpPageApiModel.cshtml

1) 从 NuGet 安装一些 Markdown 库，例如 MarkdownDeep

2) 添加助手功能。请注意，您应该修剪行，因为 <summery> 按原样解析，换行后的所有尾随空格。否则所有降价列表等都不会被正确解析。

@functions {
    string ToMarkdown(string str)
    {
        var lines = str.Split('\n');
        var whitespaceCount = 0;
        var i = 0; //from 2. Line
        var imax = lines.Count();
        while (++i < imax)
        {
            var line = lines[i];
            if (whitespaceCount != 0)
            {
                lines[i] = line.Substring(whitespaceCount);
                continue;
            }
            var trimmed = line.TrimStart();
            if (trimmed.Length == 0 || trimmed == line) continue;
            whitespaceCount = line.Length - trimmed.Length;
            i--;
        }
        str = string.Join("\n", lines);
        var md = new MarkdownDeep.Markdown {ExtraMode = true, SafeMode = false};
        return md.Transform(str);
    }
}

3) 预处理文档字符串输出

<p>@Html.Raw(ToMarkdown(description.Documentation))</p>

【讨论】：

我无法验证这个答案。所以我先投反对票。现在，我不再编写 C# 代码和 asp.net MVC 代码了。所以，我无法验证这个答案。
我已经验证了这个答案，它很棒。我现在明白了为什么在我测试之后所有额外的空白修剪都是必要的。谢谢救了我的一天。