为你的网络服务制作文档

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

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

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

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

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

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

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

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

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

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

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

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

查看本文来源