ASP的Web API帮助页面 - 链接到其他网页 [英] ASP Web API Help pages - Links to other pages
问题描述
我使用的Web API帮助页面和我希望能够包括链接到其他的方法。我从<一看到href=\"http://stackoverflow.com/questions/22985356/are-xml-documentation-tags-not-being-handled-by-web-api-2-help-pages\">Are ？XML文档标记不被网页API 2帮助页面处理中，使用＆LT;见CREF ='...'＆GT;不支持。
I am using Web API help pages and I would like to be able to include links to other methods. I have seen from Are XML documentation tags not being handled by Web API 2 help pages? that using <see cref='...'> isn't supported.
有什么比写我自己的＆LT更好的选择; A HREF ='...'＆GT;在文档中的链接，并且使用在<一个中记载的方法href=\"http://stackoverflow.com/questions/22356922/web-api-help-page-dont-escape-html-in-xml-documentation\">Web API帮助页面 - 不要逃避HTML XML文档中来得到这些＆LT; A＆GT;标签输出到帮助？这似乎很脆任何未来的变化。
Are there any better options than writing my own <a href='...'> links in the documentation, and using the method described in Web Api Help Page- don't escape html in xml documentation to get these <a> tags output to the help? It seems very brittle to any future changes.
我能想到的唯一选择是迫使API Explorer运行两次 - 一次来缓存所有不同的路线和放大器;其相应的帮助页面的URL，并第二次实际生成的文档。但我不知道在哪里挂钩这一点（或者如果它甚至有可能）
The only alternative I could think of would be to force the API explorer to run twice - once to cache all the different routes & their corresponding help page URLs, and a second time to actually generate the documentation. But I'm not sure where to hook this in (or if it's even possible)
推荐答案
我设法写的东西正确转换链接。
I have managed to write something that correctly converts links.
大纲是：
在帮助控制器的构造函数创建在CREF（如间发现字符串之间一个新的懒惰的IDictionary映射：Api.Method.Description（System.String）和相关ApiDescription
In the Help Controller's constructor create a new Lazy IDictionary mapping between the strings found in the cref (e.g. M:Api.Method.Description(System.String) and the associated 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;
});
通过这个懒到书页的各种模型（您可能需要创建额外的型号）。我已经给了他们所有的基类具有以下code：
Pass this lazy to the various models that back the pages (you may need to create extra models). I have given them all a base class with the following code:
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 "";
});
}
}
任何地方在有意见 api.Documentation.Trim（） - 或 Html.Raw（api.Documentation）如果你已经按照<一href=\"http://stackoverflow.com/questions/22356922/web-api-help-page-dont-escape-html-in-xml-documentation\">Web API帮助页面 - 不要逃避在XML文档 HTML - 你现在包装，使其成为
Anywhere in the views that had api.Documentation.Trim() - or Html.Raw(api.Documentation) if you have already followed Web Api Help Page- don't escape html in xml documentation - you now wrap so it becomes
@Html.Raw(Model.ParseDoc(api.Documentation, Url))
您会发现，要做到这一点，你需要做的各种ModelDescriptions从HelpPageModelBase继承 - （如果容易或懒惰），并通过他们传递父API模型，但它在结束工作
You will find that to do this you need to make the various ModelDescriptions inherit from HelpPageModelBase - and pass the parent API models through to them (or the Lazy if easier) but it does work in the end.
我不是这个解决方案特别高兴;你可能会发现更容易有某种形式的静态ParseDoc方法使用默认HTTP配置产生懒惰（但由于其他扩展的我做了不适合我的情况下工作）。如果你看到这样做的更好的方法，欢迎交流！希望它为您提供了一个起点。
I'm not especially happy with this solution; you might find it easier to have some form of static ParseDoc method that uses the default Http Configuration to generate the Lazy (but because of other extensions I've made that doesn't work for my case). If you see better ways of doing it, please share! Hopefully it gives you a starting point.
这篇关于ASP的Web API帮助页面 - 链接到其他网页的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
