为你的网络服务制作文档

 
介绍

一个网络服务的文档需要包含许多不同的元件。首先并且是最初，它应该提供一个有计划地描述网络服务的网络服务描述语言（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。

自定义类型

WSDL文档可以定义消息所使用的类型。当定义自定义类型时，你应该使用XSD来代替其他类型定义语言。使用XSD允许你更简单地使用WSDL相关的工具箱。这也帮助那些也许必须手工生成定制客户的人。但是，如果你看到需要定义呢自己的类型系统，你也许会－但是我不推荐。

类型在类型模块中列出。使用这个，你可以映射你自己的语言规范，为XSD请求自定义类型。如果一个棒球队希望得到一个队员的名称、平均击球、年平均击球数和队员编号，他们就应该按下面的类型定义来定义：

＜types＞

＜s:complexType name="Player"＞

＜s:sequence＞

＜s:element minOccurs="1" maxOccurs="1" name="Name" nillable="true"
type="s:string" /＞

＜s:element minOccurs="1" maxOccurs="1" name="Average"
type="s:double" /＞

＜s:element minOccurs="1" maxOccurs="1" name="Year" type="s:long" /＞

＜s:element minOccurs="1" maxOccurs="1" name="Number"
type="s:short" /＞

＜/s:sequence＞

＜/s:complexType＞
＜/types＞

这里使用了一些XML名称域，它们在文档的其他地方定义。这里要注意的重要事情是，我们有一组定义队员的元件的名称。复杂的类型Player 现在被定义了，并且可以北映射到任何不同的语言中。这种类型也指定我们怎样才能在通信时对Player 进行序列化。如果使用在一个消息中，这个元件将像下面的样子：

＜message name="PlayerMessage"＞

＜part name="thePlayer" element="s0:Player" /＞

＜/message＞

portTypes 和Bindings

WSDL也可以既对一个给定的portType 上的操作又为详细绑定的数据创建文档。相关的操作应该存在于一个给定的portType 中。这些操作间的关系代表性地用实现它们的语言片断定义。例如，如果一个COM对象和Java类给出5个方法作为网络服务，这5个方法一起来定义portType 。每个portType 都有一个匹配的binding 元件。这个binding 元件可以被用来定义portType中的每个operation 如何映射到特殊的协议中。你也许有一个按照下面定义的portType ：

＜portType name="PlayerStats"＞

＜operation name="GetBattingAverage"＞

＜input message="s0:GetBattingAverageIn" /＞

＜output message="s0:GetBattingAverageOut" /＞

＜/operation＞

＜/portType＞

这个portType 也许被许多方法所支持（重新调用那个网络服务可以通过许多协议，包括SOAP、HTTP GET和HTTP POST）。一个对SOAP的binding 也许像这样：

＜binding name="PlayerStatsSoap" type="s0:PlayerStats"＞

＜soap:binding transport=http://schemas.xmlsoap.org/soap/http
style="document" /＞

＜operation name="GetBattingAverage"＞

＜soap:operation
soapAction="http://www.seattlemariners.org/GetBattingAverage"
style="document" /＞

＜input＞

＜soap:body use="literal" /＞

＜/input＞

＜output＞

＜soap:body use="literal" /＞

＜/output＞

＜/operation＞

＜/binding＞

这个binding 元件表明这个操作将在HTTP上使用SOAP来传输。GetBattingAverage 操作使用HTTP SOAPAction 头，http://www.seattlemariners.org/GetBattingAverage 。这个操作是面向文档的并且使用文字编码。

我们也可以定义特定服务的结束点在哪。如果这个结束点可以通过一些不同的绑定来达到，例如SOAP，HTTP GET和HTTP POST，这个服务片断就会像这样：

＜service name="PlayerStats"＞

＜documentation＞Gets player information for the Seattle

Mariners.＜/documentation＞

＜port name="PlayerStatsSoap" binding="s0:PlayerStatsSoap"＞

＜soap:address
location="http://someIP/baseball1/baseballservice.asmx" /＞

＜/port＞

＜port name="PlayerStatsHttpGet" binding="s0:PlayerStatsHttpGet"＞

＜http:address
location="http://someIP/baseball1/baseballservice.asmx" /＞

＜/port＞

＜port name="PlayerStatsHttpPost" binding="s0:PlayerStatsHttpPost"＞

＜http:address
location="http://someIP/baseball1/baseballservice.asmx" /＞

＜/port＞

＜/service＞

这个特殊服务描述指出了相同的结束点，http://someIP/baseball1/baseballservice.asmx ，可以处理所有三个绑定。你也可以使用这个片断来在不同的地方描述相同的结束点。

＜service name="PlayerStats"＞

＜port name="PlayerStatsUSA" binding="s0:PlayerStatsSoap"＞

＜soap:address
location=
"http://someIPInUSA/baseball1/baseballservice.asmx" /＞

＜/port＞

＜port name="PlayerStatsJapan" binding="s0:PlayerStatsSoap"＞

＜soap:address
location=
"http://someIPInJapan/baseball1/baseballservice.asmx" /＞

＜/port＞

＜/service＞

使用文档

你的网络服务的文档也应该描述了你希望人们怎样来使用你的网络服务。解释错误将如何被返回，如何初始化使用，等等。这个信息将帮助其他人来使用你的网络服务。除非你做一些简单的事情，就像从股票行情自动收录器找到股票报价，人们就需要好的文档。

首先，包含一个总结文档。一个好的总结包括指出兵总结与网络服务相关的文档－WSDL位置，开发者指导，API参考等等。在开发者指导中，解释如何使用网络服务。描述典型使用情况，也描述错误处理。

当描述错误处理时，列出每个网络服务方法可能返回的错误。给出返回代码，这样客户程序开发者就可以查询错误代码，然后用显示消息和记录条目的方法把相应意义的消息提供给它们的最终用户。对于个性化服务，我们有一节文档来解释如何处理错误；它也提供了通常对如何处理SOAP错误的总结。然后我们指出如何发现错误代码和错误描述。我们通过提供一个指定什么样的错误存在和这些数字意味着什么地表格来在方法描述中找到这些。例如，我们写道GetFavorite 调用可以返回下面的错误：

数字 描述

1002 Invalid licensee key.

1005 Invalid user name.

作为替代在一个方法接一个方法的基础上列出错误，你也可以做一个所有网络服务可能会返回的所有错误的列表。但是，这样做的困难在于，客户程序开发者将不指定会从各种各样的代码片断返回什么样的错误。这使得编写错误处理程序对他们来说变得困难，但是却使你的文档更容易创建和保存。我们确定我们最好去做这困难的工作，而不是让开发人员通过反复试验来学习他们必须处理的错误。这要以被大多数windows API文档使用的模型为基础，在那里每个函数都列出了它们也许会返回的错误。

除了错误处理，你也会希望未网络服务中的各种操作做文档。这应该像其他API文档一样：

·解释操作做什么
　　
·定义操作的参数的意义和类型
　　
·提供示例代码
　　
·给出帮助提示

除了上面所说，在所用的通信方式（单通道，请求－响应，等等）上给出一个示例SOAP消息交换。为了感觉我们如何做这个，看一看个性化服务API参考。

你也许还希望花一些时间来定义对象或用WSDL的说法，portType 。也就是描述函数的收集并且给出用户可以从哪里找到这个WSDL文件的指针。用户程序开发人员会希望得到WSDLwenj，因此他们可以使用WSDL相关的库来调用你的网络服务。

最后，花一些时间开开发一个最常用的网络服务提供的操作的示例客户程序。确定例子看起来真的像你所期望的客户开发者也许会创建的一样。这个参考也许会提供许多你想不到的用处－开发者可以使用这个示例来验证在他们的设备中获网络服务自身的某个地方是否有问题。 　　结论

为了使你的网络服务能够成功，文档是重要的。你需要提供比使用SOAP的结束端更多的东西。使用WSDL文档描述网络服务。客户程序开发人员可以从许多代理库和使用不需要接触复杂的XML和HTTP头的结束端。WSDL在事情变坏时通过让他们知道消息是如何构造的来帮助他们。在这点上，他们需要扩充他们对SOAP的知识。WSDL给他们提供了一张地图来解释为什么他们应该查看在他们的机器和你的之间的通信。

为用户程序开发者解释各种各样的操作会返回什么样的错误。这将帮助他们编写很好的错误处理代码，因为他们会指定想要什么。如果你没有把这点说明，开发者或者过度处理错误，这会浪费他们的时间，或者他们没有错误可处理。没有错误处理会导致对网络服务的不满，而这个不满将导致你的网络服务不被使用。

最后，文档如何使用各自的操作，和给出如何调用各种操作的例子。详细描述它，并且给出诊断普通问题的信息。也要从属地为任何调用做文档。例如，大多数个性化服务中的操作掌握一点，就是调用被第一个登陆的所取得。如果你有其他依赖，你将使别人使用你的工作变得容易得多。