internationalization - wsdl :documentation tag support the xml:lang attribute?

Question

我必须为现有的 WSDL 文件编写文档，并且更愿意在文档中这样做。问题是，我找不到任何关于 wsdl:documentation 是否允许使用 xml:lang 作为属性的信息，或者是否有任何文档生成器会使用它。

到目前为止，我还没有在网上找到任何东西，我简直不敢相信我是唯一一个想做双语言文档的人。任何提示？

Answer 1

From the WSDL 1.1 specification :

WSDL uses the optional wsdl:document element as a container for human readable documentation. The content of the element is arbitrary text and elements ("mixed" in XSD). The documentation element is allowed inside any WSDL language element.

From the WSDL 2.0 specification (强调我的):

WSDL 2.0 uses the optional documentation element information item as a container for human readable or machine processable documentation. The content of the element information item is arbitrary character information items and element information items ("mixed" content in XML Schema [XML Schema: Structures]). The documentation element information item is allowed inside any WSDL 2.0 element information item.

Like other element information items in the "http://www.w3.org/ns/wsdl" namespace, the documentation element information item allows qualified attribute information items whose [namespace name] is not "http://www.w3.org/ns/wsdl". The xml:lang attribute (see [XML 1.0]) MAY be used to indicate the language used in the contents of the documentation element information item.

似乎这在 V1 中以某种方式被遗忘并在 V2 中修复。基本上，你是靠自己的。

但是，即使规范要求使用 xml:lang 文档，您也永远无法知道您的客户将使用什么来处理您提供给他们的 WSDL，也永远不知道他们是否可以正确地从中提取文档。

我希望你不介意我这么说，但我认为你以错误的方式接近这个。 Web 服务的文档不会自行恢复到 WSDL。是的，为您的客户提供 WSDL 是强制性的，以便能够轻松生成调用 Web 服务所需的管道代码，但它仅详细说明调用的技术细节。它没有说明应该如何使用您的 Web 服务。

YMMV但除了 WSDL，您可能还想:

首先概述您的 Web 服务的功能；

它的每个操作用于什么以及何时使用；

参数的含义是什么，每个参数有什么约束(例如，一些无法用 XSD 限制加强的业务约束)；

一些 SOAP 消息样本包含 Web 服务需要/返回的典型数据；

描述预期的错误，它们将具有哪些代码/描述以及如何对其进行故障排除；

强调业务限制(我在想红色粗体文字？!)；

如果要插入图片来描述整体架构怎么办？

等等

在 WSDL 中添加所有这些细节会受到限制。那么如何让您的文档由 WSDL 和一个格式良好的(特定于语言的)PDF 文件组成，其中包含我上面提到的详细信息？