Hi all,
I working in the research area of services, SLA, monitoring of QoS and
so on. This topic is really interesting for me. While in the academical
environment we look for formalize and automate the Service Level
Agreements and all this around, but how far I know in the companies, in
the real world ;) , the SLA are normally plain text documents.
So, how is your handling around this, how you negotiate, create and
document SLA, you use or tried to use any SLA formalization like WSLA,
WSAG, SLAng or what ever and what further documents (Price schema f.e.)
you have or how Christian allready ask "how people do the further
documentation that lives outside the wsdl."
Thanks and best regards
Anne
Am 21.10.2010 08:35, schrieb Christian Schneider:
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
