ASP Web API帮助页面 - 从XML链接到类< see>标签 [英] ASP Web API Help pages - Link to class from XML <see> tag

问题描述

我正在开发一个Web-API项目，我对Microsoft的帮助页面的自动生成的文档印象深刻。

I'm working on Developing a Web-API project, and i'm very impressed with the auto generated documentation by Microsoft's HelpPages.

我启用了自定义文档官方网站创建帮助页面

i enabled custom documentation using the official site creating Help Pages

文档生成成功但是没有从< See cref => ; 标签似乎被添加到描述中，HelpPages只是忽略它们（这是一个原因）。

the documentation is generated successfully BUT none of the references to Classes from the <See cref=""> Tag seems to be added to the description, the HelpPages Simply ignores them (that's for a reason).

我真的想拥有功能在我的项目，我搜索了很多（有时接近），但没有一个给出了令人信服的答案。

i really wanted to have this feature in my project, i searched a lot (got close sometimes) but none gave a convincing answer.

这就是为什么我决定发布我的解决方案这个调整，并希望有益其他程序员，并省时间和努力。
（我的答案是在下面的回复）

That's why i decided to post my solution to this tweak and hopefully benefit other programmers and spare them some time and effort. (my answer is in the replies below)

推荐答案

我的解决方案如下：

1. 您有自己的文档（从生成的xml文件）工作


2. 在文档中启用HTML和XML标签他们通常会被过滤出来，感谢您发布，您可以保留它们。
   
   只需转到： ProjectName>区域> HelpPage> XmlDocumentationProvider.cs
   
   在方法的第123行：GetTagValue（XPathNavigator parentNode，string tagName）
   
   更改代码 return node.Value .Trim（）; to return node.InnerXml;


3. 创建以下部分视图： >
   ProjectName\Areas\HelpPage\Views\Help ** _ XML_SeeTagsRenderer.cshtml **
   
   这是我的代码：

1. you've got your custom documentation (from the generated xml file) working
2. enable HTML and XML tags within the documentation, they normally get filtered out, thanks this Post you can preserve them.
   simply go to: ProjectName > Areas > HelpPage > XmlDocumentationProvider.cs
   on line 123 in method: GetTagValue(XPathNavigator parentNode, string tagName)
   change the code return node.Value.Trim(); to return node.InnerXml;
3. create the following partial view:
   ProjectName\Areas\HelpPage\Views\Help**_XML_SeeTagsRenderer.cshtml**
   this is my code:

@using System.Web.Http;
@using MyProject.Areas.HelpPage.Controllers;
@using MyProject.Areas.HelpPage;
@using MyProject.Areas.HelpPage.ModelDescriptions
@using System.Text.RegularExpressions
@model string

@{
    int @index = 0;
    string @xml = Model;
    if (@xml == null)
        @xml = "";
    Regex @seeRegex = new Regex("<( *)see( +)cref=\"([^\"]):([^\"]+)\"( *)/>");//Regex("<see cref=\"T:([^\"]+)\" />");
    Match @xmlSee = @seeRegex.Match(@xml);
    string @typeAsText = "";
    Type @tp;

    ModelDescriptionGenerator modelDescriptionGenerator = (new HelpController()).Configuration.GetModelDescriptionGenerator();

}

@if (xml !="" && xmlSee != null && xmlSee.Length > 0)
{

    while (xmlSee != null && xmlSee.Length > 0)
    {

            @MvcHtmlString.Create(@xml.Substring(@index, @xmlSee.Index - @index))

        int startingIndex = xmlSee.Value.IndexOf(':')+1;
        int endIndex = xmlSee.Value.IndexOf('"', startingIndex);
        typeAsText = xmlSee.Value.Substring(startingIndex, endIndex - startingIndex);  //.Replace("<see cref=\"T:", "").Replace("\" />", "");
        System.Reflection.Assembly ThisAssembly = typeof(ThisProject.Controllers.HomeController).Assembly;
        tp = ThisAssembly.GetType(@typeAsText);

        if (tp == null)//try another referenced project
        {
            System.Reflection.Assembly externalAssembly = typeof(MyExternalReferncedProject.AnyClassInIt).Assembly;
            tp = externalAssembly.GetType(@typeAsText);
        }  

        if (tp == null)//also another referenced project- as needed
        {
            System.Reflection.Assembly anotherExtAssembly = typeof(MyExternalReferncedProject2.AnyClassInIt).Assembly;
            tp = anotherExtAssembly .GetType(@typeAsText);
        }


        if(tp == null)//case of nested class
        {
            System.Reflection.Assembly thisAssembly = typeof(ThisProject.Controllers.HomeController).Assembly;
            //the below code is done to support detecting nested classes.
            var processedTypeString = typeAsText;
            var lastIndexofPoint = typeAsText.LastIndexOf('.');
            while (lastIndexofPoint > 0 && tp == null)
            {
                processedTypeString = processedTypeString.Insert(lastIndexofPoint, "+").Remove(lastIndexofPoint + 1, 1);
                tp = SPLocatorBLLAssembly.GetType(processedTypeString);//nested class are recognized as: namespace.outerClass+nestedClass
                lastIndexofPoint = processedTypeString.LastIndexOf('.');
            }
        }

        if (@tp != null)
        {
            ModelDescription md = modelDescriptionGenerator.GetOrCreateModelDescription(tp);
                @Html.DisplayFor(m => md.ModelType, "ModelDescriptionLink", new { modelDescription = md })            
        }
        else
        {            
                @MvcHtmlString.Create(@typeAsText)            
        }
        index = xmlSee.Index + xmlSee.Length;
        xmlSee = xmlSee.NextMatch();
    }    
            @MvcHtmlString.Create(@xml.Substring(@index, @xml.Length - @index))    
}
else
{    
        @MvcHtmlString.Create(@xml);    
}

1. 最后转到：ProjectName\Areas\HelpPage\Views\Help\DisplayTemplates ** Parameters.cshtml **
   
   在'20'行，我们有与文档中描述相对应的代码。
   
   REPLACE this：

1. Finally Go to: ProjectName\Areas\HelpPage\Views\Help\DisplayTemplates**Parameters.cshtml**
   at line '20' we have the code corresponding to the Description in the documentation.
   REPLACE this:

            <td class="parameter-documentation">
                <p>
                    @parameter.Documentation
                </p>
            </td>

有了这个：

                <td class="parameter-documentation">
                    <p>
                        @Html.Partial("_XML_SeeTagsRenderer", (@parameter.Documentation == null? "" : @parameter.Documentation.ToString()))
                    </p>
                </td>

&你必须现在工作。

注意：

& Voila you must have it working now.
Notes:

• 我尝试将HTML列表放在文档中，并呈现我很努力地尝试了多个类引用（多个< see cref =MyClass> ，我工作得很好


• 当您引用当前项目之外的类时，您不能引用在类


• 中声明的类，请添加程序集。该项目中的类的getType（检查我的代码）


• 在中找到的任何未找到的类，请参阅cref> 将在描述中打印全名（例如，如果引用属性或命名空间，代码将不会将其标识为类型/类，但将打印）

• i tried putting HTML list inside the docs and it rendered it fine
• i tried multiple class references (multiple <see cref="MyClass"> and i worked fine
• you can't refer to a class that is declared within a class
• when you refer to a class that is outside the current project please add the assembly .getType of a class within that project (check my code above)
• any un-found class found inside a <see cref> will have it's full name printed in the description (for example if you reference a property or namespace, the code won't identify it as a type/class but it will be printed)

这篇关于ASP Web API帮助页面 - 从XML链接到类< see>标签的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！