Question

情景：

我在C#中使用Web API 2.1和Visual Studio .NET 2012。

我使用///中的默认选项对代码进行评论，如下所示：

    /// <summary>
    /// This method get something and returns something.
    /// </summary>
    /// <returns>HttpResponseMessage response etc etc</returns>
    public HttpResponseMessage Get() {

我设置了XML文档文件（在build properties中），然后我获取了信息文件并在api服务帮助中显示了这一行（来自VS）

        //// Uncomment the following to use the documentation from XML documentation file.
        config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/myXMLFile.XML")));

到目前为止一切顺利，我可以在帮助区域中成功读取XML文件。但是....

问题：

我的客户将阅读此HELP文件作为第二个文档，以便通过web api连接和使用我的公开服务。但要求是帮助必须是几种语言，英语，西班牙语，德语等。

我正在考虑制作一些语言选择器＆＃34;在Web Api帮助区的家中，但我无法实现如何制作多个注释，多个XML文件或其他相关内容。

我接受过研究，但我只找到有关Sandcastle的信息（我从未使用过），我很想知道自己是否只能使用Visual Studio或Nuget Package App。

问题：

简历中：

这是否可以使用多种语言注释代码并拥有多个XML文件，并从“帮助区域”页面中选择它们？

提前致谢。请评论/编辑/评论，我很乐意改进我的问题。

更新1（2014-11-06 03:11 UTC）

此时我正在尝试修改此功能，但我无法更改/获取属性标记的值lang。

（位于XmlDocumentationProvider的{{1}}）：

Project\Areas\HelpPage\

Answer 1

我将假设您的文档documentation 是这样的

/// <summary>
/// Looks up some data by ID.
/// </summary>
/// <summary xml:lang="es">
/// Recupera algun dato por id.
/// </summary>
public string Get(int id)
{
    return "value";
}

所以我的近似是：

    public virtual string GetDocumentation(HttpActionDescriptor actionDescriptor)
    {
        XPathNavigator methodNode = GetMethodNode(actionDescriptor);
        if (methodNode != null)
        {
            XPathNavigator summaryNode = methodNode.SelectSingleNode("summary");
            if (summaryNode != null)
            {
                return string.Format("<summaries>{0}</summaries>", methodNode.InnerXml);
            }
        }

        return null;
    }

下面，您将创建一些有用的方法：

    public static string GetSummary(this ApiDescription description, string language)
    {
        string output = string.Empty;
        var summaries = description.Documentation;
        if (!string.IsNullOrEmpty(summaries))
        {
            var xmlDocument = new System.Xml.XmlDocument();
            xmlDocument.LoadXml(summaries);
            var xmlNodeList = xmlDocument.GetElementsByTagName("summary");
            if (xmlNodeList.Count > 0)
            {
                output = xmlNodeList[0].InnerText;

                for (int i = 0; i < xmlNodeList.Count; i++)
                {
                    var attribute = xmlNodeList[i].Attributes["xml:lang"];
                    if (attribute!= null && attribute.InnerText == language)
                    {
                        output = xmlNodeList[i].InnerText;
                    }
                }
            }
        }

        return output;
    }

然后，您在视图中使用它们，例如在\ Areas \ HelpPage \ Views \ Help \ DisplayTemplates \ HelpPageApiModel.cshtml

中

 <p>@description.GetSummary(@ViewContext.RouteData.Values["language"].ToString())</p>

最后，修改路线：

 context.MapRoute(
            "HelpPage_Default",
            "Help/{language}/{action}/{apiId}",
            new { controller = "Help", language = "en", action = "Index", apiId = UrlParameter.Optional });

帮助页面的链接是：

... /帮助/ ES /原料药/ GET-API值-ID
... /帮助/ EN /原料药/ GET-API值-ID

Answer 2

尝试使用Localized Help Page。它允许您编写如下的本地化注释：

/// <summary>Gets a value</summary>
/// <param name="id">ID of the value</param>
/// <returns>Value</returns>
/// <summary xml:lang="de-DE">...</summary>
/// <param name="id" xml:lang="de-DE">...</param>
/// <returns xml:lang="de-DE">...</returns>
public string Get(int id)
{
    return "value";
}

然后它会为每种语言生成一个单独的帮助页面。

如何以多种语言提供Web / API帮助？

情景：

问题：

问题：

更新1（2014-11-06 03:11 UTC）

2 个答案: