Some time ago I needed to produce some documentation describing existing soap webservices. I looked into other tools that already do this, but none of them produced the output in a format that suited me, also the schema for the webservice has literally hundreds of options that were rarely or never used, or were never or no longer supported. I thought that using the existing tools would make the reader even more confused.

Luckily the schemas used the xs:documentation field extensively, and were properly created with restrictions and so on.

The approach I decided to take was to take an existing request and response sample and document that using the WSDL/Schema.

The xsl I created was quick and dirty, it has lots of flaws, including:

• It can sometimes match with wrong fields in the schema, this is because I don’t maintain the complete hierarchy when running, so if two elements have the same name, it might pick the incorrect one.
• The schemas must be flattened, that is, if you include external files it will not use them. This was easy enough to overcome using the excellent WSDLFlattener at the xmlhelpline.

It worked well enough for the documents I needed to create, and saved me some weeks of work doing this manually.

The output is html and looks like this:

To use it:

• Download the zip file here and expand it somewhere convenient.
• Download a XSLT Parser like xalan.

Edit the .bat file and set the location of xalan, and where you want the output to be saved. From a command prompt:

 rq-rs-doc.bat <WSDL or XSD file> <sample xml file>

This will create a file in the an html file documenting the XML.

Lastly, I would also like to acknowledge that I based this on XML to HTML Verbatim Formatter with Syntax Highlighting by Oliver Becker.

Last modified on 2012-07-12