Search code examples
soapwsdlsoapui

Creating a comment that gets displayed in generated request? WSDL SOAP xml

Im in the process of writing a wsdl file for an existing system. I'd like to add comments to generated requests.

For instance this: 

    <xsd:simpleType name="coffeetype">
        <xsd:restriction base="xsd:integer">
            <!--0=likescoffee,1=doesnotlikecoffe-->
            <xsd:enumeration value="0" />
            <xsd:enumeration value="1" />
        </xsd:restriction>
    </xsd:simpleType>
    <xsd:element name="CoffeeRequestInput" nillable="false" type="tns:coffeetype" />

Should look like this in the generated request: (eg. when loading the WSDL in SoapUI)

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsdl="https://example.com/some.wsdl">
   <soapenv:Header/>
   <soapenv:Body>
      <!--0=likescoffee,1=doesnotlikecoffe-->
      <wsdl:CoffeeRequestInput>0</wsdl:CoffeeRequestInput>
   </soapenv:Body>
</soapenv:Envelope>

I was able to see these comments when opening the WSDL but not when generating a request from that WSDL.

Already looked into annotations but I wasn't able to use them to create the result I wanted. (Probably an error on my side)

Solution

  • In short you cannot create documentation in requests as you would like to. However you can generate documentation from your WSDL that can be be very useful. By using the "xsd:documentation" tag you can add documentation directly to the elements.

    For example

    <xsd:simpleType name="coffeetype">
    <xsd:restriction base="xsd:integer">

        <xsd:enumeration value="0" />
        <xsd:enumeration value="1" />
    </xsd:restriction>
</xsd:simpleType>
<xsd:element name="CoffeeRequestInput" nillable="false" type="tns:coffeetype">
    <xsd:annotation>
        <xsd:documentation>
          This object is the CoffeeRequestInput object is an Enumeration which can be used to determine is the user sending the request likes coffee or not. 
           Valid values for the enumeration is as follows:
           0 = like coffee
           1 = does not like coffee (probably a user not a programmer making a request).
           Some other things that you need to document goes here.
        </xsd:documentation>   
    </xsd:annotation>
</xsd:element>

    You can then use software such as Altova StyleForce, LiquidXML and OxyGen to generate PDF, Word documents or HTML pages which shows the SOAP services and operations with all your comments included.

    If you feel up to it you can write your own XLST to transform your WSDL and XSD's into a neat HTML page which documents you interfaces as well. The best part about this is that when you update the WSDL with new operations and so on that the documentation is updated as well.