如何使用多种语言提供Web/API帮助

本文关键字：Web API 帮助 何使用 语言 | 更新日期: 2023-09-27 18:29:28

场景：

我在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文件但是。。。。

问题：

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

我想在Web Api帮助区的主页上制作一些"语言选择器"，但我不知道如何制作多个注释、多个XML文件或相关的东西。

我进行了研究，但我只找到了关于Sandcastle的信息（我从未使用过它），我想知道是否可以只使用Visual Studio或一些Nuget Package应用程序。

问题：

简历中：

这是否可以用几种语言和几个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;
}

如何使用多种语言提供Web/API帮助

我假设您的文档文档像这个吗

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

帮助页面的链接是：

  • /Help/es/Api/GET Api值id
  • /帮助/en/Api/GET-Api值id

尝试使用本地化帮助页面。它允许你写这样的本地化评论：

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

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

相关文章：