documentation generated from .wsdl

[Michael Potter-3]

wsdl list,

I have a need to document our webservices in a format usable by
non-technical users.

What I have in mind is some additional markup in my .wsdl files that I
will filter and use to generate .pdf/.html files.  This would be done in the
spirit of javadoc for java and pod for perl.

My questions are:
1) Has anyone already done such a thing?
2) Is there a standard way to do that?

I am guessing that such a tool would use the
<xs:annotation>
<xs:documentation xml:lang="en">
<wsdl:documentation>
tags.

To be useful the tool would need to do more than just read those tags.
 Much like javadoc requires the comments in java to have a particular
format, the tool would have to have the mentioned tags to have a
specific format.

I apologize if this is not the correct forum for such a question.  If
you could point me to a proper forum I would appreciate it.

The context of this question is that I have 1200 webservices and would
like to produce documentation that is suitable for a sales situation.
I would like to maintain that documentation in the .wsdl file or other
source code so that it would stay up-to-date.

--
Michael Potter

[Arthur Ryman-2]

Mike,

Yes, wsdldoc processors exist. They produce documentation similar to javadoc. The approach is to use the <documentation> tags that are part of the wsdl markup.

I work at IBM and know of support for generating documentation in our tool products like Rational Application Developer. Craig and Keith can tell you about that. The tools also generate xsddoc for any schemas referenced from the wsdl. I believe some diagrams are also generated in the current version.

There is no standard for this, but since both wsdl and xsd are xml, you should easily be able to use xslt and fop to generate simple html and pdf documentation.

Arthur Ryman, PhD, AoT, DE
Process and Portfolio Management, Rational Division

phone: [phone], TL 969-3077
assistant: [phone] (T/L: 318-8867)
fax: [phone], TL 969-4920
mobile: [phone], text: 4169395063@...

"Michael Potter" <pottmi@...>
Sent by: www-ws-desc-request@...

08/09/2007 03:04 PM

To	www-ws-desc@...
cc
Subject	documentation generated from .wsdl

wsdl list,

I have a need to document our webservices in a format usable by
non-technical users.

What I have in mind is some additional markup in my .wsdl files that I
will filter and use to generate .pdf/.html files.  This would be done in the
spirit of javadoc for java and pod for perl.

My questions are:
1) Has anyone already done such a thing?
2) Is there a standard way to do that?

I am guessing that such a tool would use the
<xs:annotation>
<xs:documentation xml:lang="en">
<wsdl:documentation>
tags.

To be useful the tool would need to do more than just read those tags.
Much like javadoc requires the comments in java to have a particular
format, the tool would have to have the mentioned tags to have a
specific format.

I apologize if this is not the correct forum for such a question.  If
you could point me to a proper forum I would appreciate it.

The context of this question is that I have 1200 webservices and would
like to produce documentation that is suitable for a sales situation.
I would like to maintain that documentation in the .wsdl file or other
source code so that it would stay up-to-date.

--
Michael Potter

[Frank Baxter]

Michael Potter-3 wrote:

I have a need to document our webservices in a format usable by
non-technical users.

Does anyone have any pointer to tools?  I've started looking for this as well and I can't find anything that is still a viable product.

IBM had an ETTK back in 2003 that had a WSDLDoc tool in it.  I tried the tool but it doesn't include my schema files.

Bluetetra had a tool, also back in 2003, and also called WSDLDoc that seemed ver promising.  Unfortunately the company appears to be defunct.  I was able to run and use the tool though.

Other than these 2 tools I can't find anything that does documentation for WSDL.  I would think this would be a real need.

[tomi vanek]

Michael Potter-3 wrote:

I have a need to document our webservices in a format usable by non-technical users.

Maybe you could find useful my tool for WSDL documentation generation: the wsdl-viewer.xsl (http://tomi.vanek.sk/index.php?page=wsdl-viewer). This is just an XSLT 1.0 transformation that can run in any browser. The transformation converts WSDL into easier understandable HTML format. You can create the documentation either with batch processing (i.e. by ANT script), or simply by adding a processing instruction into WSDL, so by opening the WSDL in a browser the XML will be instantly converted into HTML.

[Arthur Ryman-2]

Tomi,

I see this is for WSDL 1.1. Have you thought of supporting WSDL 2.0? If you want to contribute your code, maybe the Apache Woden project [1] could provide a home.

Another thought is to leverage the WSDL 2.0 Component Model Interchange format [2] - an XML format that combines the content of multiple WSDL 2.0 and XSD files (via import and include) into a single file. This format is used in the Test Suit and is implemented by Woden.

[1] http://incubator.apache.org/woden/
[2] http://dev.w3.org/cvsweb/2002/ws/desc/test-suite/interchange/

Arthur Ryman, PhD, AoT, DE
Process and Portfolio Management, Rational Division

phone: [phone], TL 969-3077
assistant: [phone] (T/L: 318-8867)
fax: [phone], TL 969-4920
mobile: [phone], text: 4169395063@...

tomi vanek <tomi.vanek@...>
Sent by: www-ws-desc-request@...

10/04/2007 10:22 AM

To	www-ws-desc@...
cc
Subject	Re: documentation generated from .wsdl

Michael Potter-3 wrote:
I have a need to document our webservices in a format usable by non-technical users.
Maybe you could find useful my tool for WSDL documentation generation: the wsdl-viewer.xsl (http://tomi.vanek.sk/index.php?page=wsdl-viewer). This is just an XSLT 1.0 transformation that can run in any browser. The transformation converts WSDL into easier understandable HTML format. You can create the documentation either with batch processing (i.e. by ANT script), or simply by adding a processing instruction into WSDL, so by opening the WSDL in a browser the XML will be instantly converted into HTML.

---

View this message in context: Re: documentation generated from .wsdl
Sent from the w3.org - www-ws-desc mailing list archive at Nabble.com.

[Jonathan Marsh-2]

Some parts of this message have been removed. Learn more about Nabble's security policy.

Tomi,

 

I like the view you’ve created, and would encourage a WSDL 2.0 equivalent as well!  In conjunction with conventions for how structured <wsdl:documentation> elements could be added to the display it would make an invaluable tool.  I generate something similar but much more limited from the WSDL [0], in this case abstracting out the differences between WSDL 1.1 and WSDL 2.0 representations of the service.

 

Incidentally I’ve also done something similar to your source code appendix but a little more elaborate – an xslt stylesheet that pretty-prints the source code of the WSDL and then makes QName and URI references clickable for easy navigation, annotates items with their back-links, and generates indexes of the constructs.  Stylesheets are available for WSDL 1.1, WSDL 2.0, and XML Schema 1.0.  You can get them at [1], or you can see an annotated WSDL 2.0 example at [2], or the annotated schema for schemas at [3].  They’re under the Apache Open Source License.

 

[0] http://mashups.wso2.org/services/storexml?doc

[1] http://wso2.org/repos/wso2/trunk/commons/annotated-stylesheets/readme.htm

[2] http://mashups.wso2.org/services/LatestEarthquakes?wsdl2&annotation=true

[3] http://wso2.org/repos/wso2/trunk/commons/annotated-stylesheets/XMLSchema.xsd

 

Jonathan Marsh - http://www.wso2.com - http://auburnmarshes.spaces.live.com

 

From: www-ws-desc-request@... [mailto:www-ws-desc-request@...] On Behalf Of Arthur Ryman
Sent: Friday, October 05, 2007 1:08 PM
To: tomi vanek
Cc: www-ws-desc@...; www-ws-desc-request@...
Subject: Re: documentation generated from .wsdl

 

Tomi,

I see this is for WSDL 1.1. Have you thought of supporting WSDL 2.0? If you want to contribute your code, maybe the Apache Woden project [1] could provide a home.

Another thought is to leverage the WSDL 2.0 Component Model Interchange format [2] - an XML format that combines the content of multiple WSDL 2.0 and XSD files (via import and include) into a single file. This format is used in the Test Suit and is implemented by Woden.

[1] http://incubator.apache.org/woden/
[2] http://dev.w3.org/cvsweb/2002/ws/desc/test-suite/interchange/

Arthur Ryman, PhD, AoT, DE
Process and Portfolio Management, Rational Division

phone: [phone], TL 969-3077
assistant: [phone] (T/L: 318-8867)
fax: [phone], TL 969-4920
mobile: [phone], text: 4169395063@...

tomi vanek <tomi.vanek@...>
Sent by: www-ws-desc-request@...

10/04/2007 10:22 AM

To	www-ws-desc@...
cc
Subject	Re: documentation generated from .wsdl

 

Michael Potter-3 wrote:
I have a need to document our webservices in a format usable by non-technical users.
Maybe you could find useful my tool for WSDL documentation generation: the wsdl-viewer.xsl (http://tomi.vanek.sk/index.php?page=wsdl-viewer). This is just an XSLT 1.0 transformation that can run in any browser. The transformation converts WSDL into easier understandable HTML format. You can create the documentation either with batch processing (i.e. by ANT script), or simply by adding a processing instruction into WSDL, so by opening the WSDL in a browser the XML will be instantly converted into HTML.

---

View this message in context: Re: documentation generated from .wsdl
Sent from the w3.org - www-ws-desc mailing list archive at Nabble.com.