c# - 如何制作多种语言的 Web/API 帮助？

Question

场景:

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

我在 /// 中使用默认选项评论代码，如下所示:

    /// <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 文件。但是....

---

问题:

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

我想在 Web Api 帮助区的主页中制作一些“语言选择器”，但我无法实现如何制作多个评论、多个 XML 文件或相关内容。

我进行了研究，但我只找到了有关 SandcaSTLe 的信息(我从未使用过它)，我想知道是否可以仅使用 Visual Studio 或某些 Nuget Package App 来完成。

---

问题:

在简历中:

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

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

---

更新 1(2014-11-06 03:11 UTC)

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

(位于 Project\Areas\HelpPage\ 中的 XmlDocumentationProvider):

public virtual string GetDocumentation(HttpActionDescriptor actionDescriptor)
{
    XPathNavigator methodNode = GetMethodNode(actionDescriptor);
    if (methodNode != null)
    {
        XPathNavigator summaryNode = methodNode.SelectSingleNode("summary");
        if (summaryNode != null)
        {
            return summaryNode.Value.Trim();
        }
    }

    return null;
}

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;
    }

然后，您在 View 中使用它们，例如在\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 });

帮助页面的链接是:

• .../Help/es/Api/GET-api-Values-id
• .../Help/en/Api/GET-api-Values-id