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 回答