2

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

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

4

1 回答 1

3

从 WSDL 1.1 规范

WSDL 使用可选的 wsdl:document 元素作为人类可读文档的容器。元素的内容是任意文本和元素(XSD 中的“混合”)。任何 WSDL 语言元素中都允许使用文档元素。

从 WSDL 2.0 规范(强调我的):

WSDL 2.0 使用可选的文档元素信息项作为人类可读或机器可处理文档的容器。元素信息项的内容是任意的字符信息项和元素信息项(XML Schema [XML Schema: Structures]中的“混合”内容)。文档元素信息项允许在任何 WSDL 2.0 元素信息项中。

与“ http://www.w3.org/ns/wsdl ”命名空间中的其他元素信息项一样,文档元素信息项允许其[命名空间名称]不是“ http://www.w3”的限定属性信息项。组织/ns/wsdl ”。xml:lang 属性(参见 [XML 1.0])可用于指示文档元素信息项的内容中使用的语言

似乎这在 V1 中以某种方式被遗忘并在 V2 中修复。基本上,你是一个人。

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

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

YMMV,但在 WSDL 之外,您可能想要:

  • 首先概述您的 Web 服务的功能;
  • 其每项操作的用途和时间;
  • 参数的含义是什么,每个参数都有哪些约束(例如,一些无法通过 XSD 限制加强的业务约束);
  • 一些包含 Web 服务所需/返回的典型数据的 SOAP 消息样本;
  • 描述预期的错误、它们将具有哪些代码/描述以及如何解决它们;
  • 强调业务限制(我在想红色粗体字?!);
  • 如果要插入图片来描述整体架构怎么办?
  • 等等等等

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

于 2012-12-08T19:52:52.363 回答