I know that the wsdl stuff like methods can be documented. The real
interesting stuff is the schema though. As you said documentation for
the schema depends on jaxb. So I guess the jaxb team has to add the feature.
I just checked their issues and found some:
https://jaxb.dev.java.net/issues/show_bug.cgi?id=273
https://jaxb.dev.java.net/issues/show_bug.cgi?id=369
https://jaxb.dev.java.net/issues/show_bug.cgi?id=460
Anyway I am more interested in how people do the further documentation
that lives outside the wsdl. I guess anyone who seriously uses services
has a lot more documentation than only the wsdl.
Best Regards
Christian
Am 20.10.2010 20:57, schrieb Daniel Kulp:
On Wednesday 20 October 2010 9:42:35 am Schneider Christian wrote:
Hi All,
I am currently making a concept how to do service documentation at my
company. One of the problems is documenting the service contract.
At the moment we use a wiki where we create one page per service with some
technical and business documentation. Of course the WSDL is linked the but
it only shows the syntax not the semantic. So we additionally document
each method and data structure in the wiki. The problem is that the wiki
will not notice when the structure of the contract changes so it is quite
tedious manual work to keep them in sync. A nice addition we recently did
is to refrence the wsdl viewer xslt from tomi vanek in our wsdls
(http://tomi.vanek.sk/index.php?page=wsdl-viewer). This formats the wsdl
as a web page that you can even show the business people.
We could also add documentation elements to the wsdl but this has two
problems. The first is that we generate the wsdls out of java code (as it
is easier than writing wsdls by hand) and the generation does not support
generating documentation.
Well, if you upgrade to CXF 2.3.0, we DO have the @WSDLDocumentation
annotations to allow you to provide additional documentation into the
generated WSDL. It only allows into the wsdl constructs and not the schema
stuff (generated from the databinding such as JAXB), but that would provide
some documentation.
Dan
The other and bigger problem is that the
dcoumentation in the wsdl is much more difficult to change especially
comapred with the ease of use of a wiki.
So my question is: How do you document your services? Do you use some
clever low tech solutions? Did you write your own kind of repository or do
you use a commercial or open source product?
Thanks
Christian
Christian Schneider
Informationsverarbeitung
Business Solutions
Handel und Dispatching
Tel : +49-(0)721-63-15482
EnBW Systeme Infrastruktur Support GmbH
Sitz der Gesellschaft: Karlsruhe
Handelsregister: Amtsgericht Mannheim ‑ HRB 108550
Vorsitzender des Aufsichtsrats: Dr. Bernhard Beck
Geschäftsführer: Jochen Adenau, Hans-Günther Meier
--
----
http://www.liquid-reality.de
