Question

我正在使用Web API帮助页面，我希望能够包含其他方法的链接。我从Are XML documentation tags not being handled by Web API 2 help pages?看到使用＆lt; see cref =＆＃39; ...＆＃39;＆gt;不受支持。

有没有更好的选择，而不是写我自己的＆lt; a href =＆＃39; ...＆＃39;＆gt;文档中的链接，并使用Web Api Help Page- don't escape html in xml documentation中描述的方法来获取这些＆lt; a＆gt;标签输出到帮助？对于未来的任何变化，它似乎都非常脆弱。

我能想到的唯一选择是强制API浏览器运行两次 - 一次缓存所有不同的路由＆amp;他们相应的帮助页面URL，以及第二次实际生成文档。但我不知道在哪里挂钩（或者如果它可能的话）

Answer 1

我设法编写了正确转换链接的内容。

概要是：

在Help Controller的构造函数中，在cref中找到的字符串之间创建一个新的Lazy IDictionary映射（例如M：Api.Method.Description（System.String）和相关的ApiDescription

        _methodReferences = new Lazy<IDictionary<string, ApiDescription>>(() => {
            var dictionary = new Dictionary<string, ApiDescription>();

            var apiExplorer = new ApiExplorer(config);

            foreach (var apiDescription in apiExplorer.ApiDescriptions)
            {
                var descriptor = apiDescription.ActionDescriptor as ReflectedHttpActionDescriptor;
                if (descriptor != null)
                {
                    var methodName = string.Format(
                        @"M:{0}.{1}({2})",
                        descriptor.MethodInfo.DeclaringType.FullName,
                        descriptor.MethodInfo.Name,
                        string.Join(@",",descriptor.GetParameters().Select(x => x.ParameterType.FullName))
                        );
                    dictionary[methodName] = apiDescription;
                }

            }
            return dictionary;
        });

将这种懒惰传递给支持页面的各种模型（您可能需要创建额外的模型）。我已经使用以下代码为它们提供了所有基类：

public abstract class HelpPageModelBase
{
    private static Regex _seeRegex = new Regex("<see cref=\"([^\"]+)\" />");
    private readonly Lazy<IDictionary<string, ApiDescription>> _methodReferences;

    protected HelpPageModelBase(Lazy<IDictionary<string, ApiDescription>> methodReferences)
    {
        _methodReferences = methodReferences;
    }

    protected HelpPageModelBase(HelpPageModelBase parent)
    {
        _methodReferences = parent._methodReferences;
    }

    public string ParseDoc(string documentation, UrlHelper url)
    {
        if (documentation == null)
        {
            return null;
        }
        return _seeRegex.Replace(documentation,
                                 match => {
                                     if (_methodReferences.Value.ContainsKey(match.Groups[1].Value))
                                     {
                                         var descriptor = _methodReferences.Value[match.Groups[1].Value];

                                         return string.Format(@"<a href='{0}'>{1} {2}</a>",
                                                              url.Action("Api",
                                                                         "Help",
                                                                         new {
                                                                             apiId = descriptor.GetFriendlyId()

                                                                         }),
                                                              descriptor.HttpMethod.Method,
                                                              descriptor.RelativePath
                                             );
                                     }
                                     return "";
                                 });
    }
}

如果您已经关注Web Api Help Page- don't escape html in xml documentation，则api.Documentation.Trim() - 或Html.Raw(api.Documentation)视图中的任意位置 - 您现在将其换行以便

@Html.Raw(Model.ParseDoc(api.Documentation, Url))

你会发现要做到这一点，你需要让各种ModelDescriptions继承自HelpPageModelBase - 并将父API模型传递给它们（如果更容易，则传递给Lazy），但它最终会起作用。

我对此解决方案并不特别满意;您可能会发现使用某种形式的静态ParseDoc方法更容易，该方法使用默认的Http配置来生成Lazy（但由于我已经做出的其他扩展，我的情况并不适用）。如果您看到更好的方法，请分享！希望它能给你一个起点。

ASP Web API帮助页面 - 指向其他页面的链接

1 个答案: