为网络服务制作文档

　　如果你阅读了我们上一个专栏，你也许会期待一篇关于互用性的文章。由于它失败了，近来我已经更多地考虑文档而不是关于互用性，因此在这篇文章中我们将看一看如何为一个网络服务做文档。（这将花去我一些时间来创建一些在非Microsoft工具箱中运行的好例子。它值得等待。）

　　一个网络服务的文档需要包含许多不同的元件。首先并且是最初，它应该提供一个有计划地描述网络服务的网络服务描述语言（WSDL）文件。第二，它需要提供一份写好的文档，来描述如何使用网络服务。这应该包含各种项目，包括一个API参考，问题和解决技巧合用法描述。最后，这份文档应该为所有操作提供实例代码，最好使用所需要的最少的代码来调用所给的方法。传来和送走的SOAP消息的例子应该与代码在一起。这些示例消息将帮助开发人员用不同于示例中给出的语言开发一个客户程序。理想情况下，文档也应该包含一个使用网络服务的示例用户，用源代码完成。

　　在这个专栏中，我将调查为什么需要这个信息并解释它的价值。在一些站点，如XMethods，今天可以得到的许多网络服务都有简单的接口，并且返回信息，就像根据邮政区码给出的当前温度。但是，将来商业网络服务将有更丰富和更复杂的接口；它们将需要文档来描述它们的使用方法。 WSDL文件

　　当为一个网络服务做文档时，你必须提供一个WSDL文档。这个文档提供了关于网络服务的重要信息，开发者和编程工具都需要这些信息。用一个紧凑具体的方法，这个文档描述所有事情，包括：

　　·网络服务所理解的消息和对那些消息响应的格式
　　·服务支持的协议
　　·把消息送到哪

　　所有这些信息使程序员对系统希望外部应用程序如何与网络服务相互作用有一个了解。因此，WSDL是你的用户所需要的文档的主要部分。

　　记住，例子和详述文档对于非琐碎的网络服务来说总是需要的。没有例子和详述文档，开发者所编的网络服务也许不会像你打算的那样使用服务，或者也许会遇到问题并且因为受挫而放弃。 一个WSDL文档总是有definitions 元件作为它的根。文档中指定WSDL的元件都术语WSDL名字域，它的URL是http://schemas.xmlsoap.org/wsdl/。任何WSDL语言元件可以包含名为document 的另一个元件。这个元件包含了人类可读的文本并且意味着把所包含的元件用文档说明。document 元件可以包含任意的文本和元件。WSDL指定的元件有：

　　1.types: 描述message使用的类型
　　2.message: 定义在调用时从一点传到另一点的数据
　　3.portType: 定义operation的收集
　　4.operation: 定义input, output, 和fault 消息的综合
　　5.input: 一个被发送到服务器上的 message
　　6.output: 一个发送到用户的message
　　7.fault: 一个作为处理message 的错误的结果返回的数值
　　8.binding: 描述用来承担网络服务的通信的协议；捆绑了现有的SOAP, HTTP GET, HTTP POST, 和MIME
　　9.service: 定义了port的收集；每个service 要映射到一个portType 中并且表现出访问那个portType 中operation 的不同方法这些元件中的许多还包含可扩展性元件。可扩展性元件定义了所给的传输的各种特性如何能被映射到那个特殊元件中。例如，在一个使用SOAP绑定的操作元件中，你可以指定SOAPAction 和通信的方式（RPC或文档）。

　　这节中将给出关于WSDL文件所提供的项目的一个简短总结。对于完全的总结，参考WSDL规范，位于Web Services Description Language (WSDL) 1.1。