Good Web service design starts with a schema. Binding, port type and all these
other parameters of a WSDL file usually are not interesting at all – 99.9% of
all services have trivial SOAP bindings, no headers and no declared faults. Also,
majority of Web services today are document-style with one “part” per message.
So schemas of input and output messages are really the key to understanding what
service is about. In other words, schema truly defines the contract of a service.
There is no substitution for the schema – you can’t generate a good schema from
a source code or a UML class diagram since they do not convey optionality,
restrictions, patterns, element model (sequence or choice) and other aspect. XML
Schema is verbose and complex (and that’s a topic for another post), but it is
pretty expressive as far the data typing goes.
So I usually start a service design with a well-documented schema. The question
is, however, how to then publish it so other people can review it (you know,
people who represent service consuming applications – these folks are kind of
important). Reviewing a schema in a “raw” format is out of question, especially
if business people are involved. So a nicely formatted HTML documentation which
could present the schema in a readable format (ideally, translating schema lingo
into plain English, such as “minOccur=0 ” could translate into “optional”) is
the way to go.
I suspect that SOA registries, such as Infravio, can take care of this problem.
But oftentimes there is a need to prototype a solution quickly before SOA
infrastructure is put into place. Also, at this day and age, open source/free/inexpensive
tools might be a requirement for many projects.
The best known Schema documentation generator is xnsdoc.
It is not free, but 49 EUR seems like a reasonable price. xnsdoc has an open
source XSLT-based counterpart with fewer capabilities. xnsdoc does produce nice
documentation along the lines of JavaDoc format (although I’m not convinced that
this is the best choice – remember, the documentation has to be suitable for non-developers),
however, in my view it does not do much in terms of explaining the schema in
plain English. In other words, the assumption is that users are familiar with
Schema concepts. I also found that the support for groups and multi-files
schemas had some problems (but keep in mind that I’d done my testing almost a
year back, so please check the latest version)
A better tool that I found is Bluetetra
XSDDoc (99 USD). In my view, it provides more user-friendly schema
documentations. You can see some examples here.
Unfortunately, it is not clear if XSDDoc is still actively supported – its
website provides only minimal information and the product has not been updated
in a while.
I still think that there is a need for more interactive Wiki-style schema
publishing tool that would allow users reviews schemas expressed in layman terms
and comment on elements and types.