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 -- Daniel Kulp [email protected] http://dankulp.com/blog
