Documenting with Web Service Definition Language (WSDL) Files

The power of TechWriter comes from its ability to leverage information from your web service. In this topic we will show you how to document web services based on Web Service Definition Language (WSDL) files by including comments directly within the WSDL itself as an alternative to creating annotations within TechWriter. Comments can include simple text descriptions or richly formatted content depending on the comment model you wish to use.

Documenting Services and Methods

WSDLs include the documentation tag as part of the web service definition that can be used to create comments for the service and its methods. For service comments, simply include the documentation tag with your comments nested inside the service tag. For method comments, simply include the documentation tag with your comments nested inside the operation tag that defines the method.

Here is an example of a documentation tag being used to associate comments with a service:

<wsdl:service name="WeatherForecast">
    <wsdl:documentation>
Service for getting the latest weather forecast.
</wsdl:documentation>
    <wsdl:port name="WeatherForecastSoap" binding="tns:WeatherForecastSoap">
      <soap:address location="http://localhost/WeatherForcast.asmx" />
    </wsdl:port>
</wsdl:service>

Here is an example of a documentation tag being used to associate comments with a method:

<wsdl:portType name="WeatherForecastPortType">
    <wsdl:operation name="GetTenDayForecast">
    <wsdl:documentation>
Method for getting the weather forecast for the next 10 days.
</wsdl:documentation>
      <wsdl:input message="tns:GetTenDayForecast" />
<wsdl:output message="tns:GetTenDayForecastResponse" />

    </wsdl:port>
</wsdl:service>

Documenting Method Arguments

Web service methods can be defined to use either a RPC or Document style interface. While arguments using either style of interface can be documented, the mechanism is slightly different for each of them.

For Document-style arguments, the structure of the requests and responses are defined using XML Schema Definition (XSD) elements and types that can either be included in the WSDL or imported from an external XML Schema. The annotation tag can be used to create comments for these element and type definitions. Simply include the annotation tag with your comments for each item you wish to document.

Here is an example of a documentation tag being used to associate comments with a document-style method argument:

<xsd:simpleType name="ZipCodeType">
    <xsd:annotation>
       <xsd:documentation>Contains a 5-digit US ZIP code.</xsd:documentation>
    </xsd:annotation>
:
</xsd:simpleType>

For RPC-style arguments, each argument is defined by a different part tag that makes up the input or output message. For this style of argument, simply include the documentation tag with your description inside the part tag that defines the argument.

Here is an example of a documentation tag being used to associate comments with an RPC-style method argument:

<wsdl:part name="ZipCodeType" type="xsd:string">
    <xsd:documentation>Contains a 5-digit US ZIP code.</xsd:documentation>
</wsdl:part>

Documenting Methods and Arguments using Comment Tags

Depending on the type of web service toolkit you are using, it is possible that you will not have complete control of the WSDL. Some tools will generate all or part of the WSDL dynamically for you. In these cases, you may find that you are unable to document your method arguments because the tool you are using does not provide a way to specify the appropriate documentation tags. To workaround this limitation, TechWriter supports the use of comment tags within the comments associated with the method to document the method arguments. For example, the JavaDoc param tag can be used to include argument descriptions within the method comments as shown below.

<wsdl:portType name="GetForecastPortType">
    <wsdl:operation name="GetForecast">
    <wsdl:documentation>
Method for getting a weather forecast.
@param startDate Specifies the first day of the weather forecast.
@param endDate Specifies the last day of the weather forecast.
@return The weather forecast for the specified date range.
</wsdl:documentation>
      <wsdl:input message="tns:GetForecast" />
<wsdl:output message="tns:GetForecastResponse" />
    </wsdl:port>
</wsdl:service>

For RPC-style methods, the name following the @param must match a part name specified in either the input or output message. For Document-style methods, the name must match an element name contained within either the input or output document type.

In order to use comment tags, you must select the proper comment model for your database from the Web Service Settings dialog that is displayed when you add or edit a web service for the project.

Formatting Options

In some instances, you may want to format your comments with multiple paragraphs, lists, links and other formatting options that are available when using TechWriter's Annotation editor. By using one of TechWriter's supported comment models, such as XHTML, you can apply formatting to the text using comment tags. In order to use comment tags you must select the proper comment model for your WSDL from the Web Service Settings dialog that is displayed when you add or edit a WSDL for the project.