RE: documentation generated from .wsdl
"Jonathan Marsh" <[email protected]> Tue, 9 Oct 2007 11:27:51 -0700
| Newsgroups | gmane.comp.web.services.description |
|---|---|
| Message-ID | <008a01c80aa2$1ac8dc10$505a9430$@com> |
This is a multipart message in MIME format. ------=_NextPart_000_008B_01C80A67.6E6A0410 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit 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 <http://mashups.wso2.org/services/LatestEarthquakes?wsdl2&annotation=true> &annotation=true [3] http://wso2.org/repos/wso2/trunk/commons/annotated-stylesheets/XMLSchema.xsd Jonathan Marsh - <http://www.wso2.com> http://www.wso2.com - <http://auburnmarshes.spaces.live.com> http://auburnmarshes.spaces.live.com From: [email protected] [mailto:[email protected]] On Behalf Of Arthur Ryman Sent: Friday, October 05, 2007 1:08 PM To: tomi vanek Cc: [email protected]; [email protected] 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: +1-905-413-3077, TL 969-3077 assistant: +1-905-413-3831 (T/L: 318-8867) fax: +1-905-413-4920, TL 969-4920 mobile: +1-416-939-5063, text: [email protected] tomi vanek <[email protected]> Sent by: [email protected] 10/04/2007 10:22 AM To [email protected] 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> 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: <http://www.nabble.com/documentation-generated-from-.wsdl-tf4245751.html#a13 040893> documentation generated from .wsdl Sent from the w3.org <http://www.nabble.com/w3.org---www-ws-desc-f11747.html> - www-ws-desc mailing list archive at Nabble.com. ------=_NextPart_000_008B_01C80A67.6E6A0410 Content-Type: text/html; charset="us-ascii" Content-Transfer-Encoding: quoted-printable <html xmlns:v=3D"urn:schemas-microsoft-com:vml" = xmlns:o=3D"urn:schemas-microsoft-com:office:office" = xmlns:w=3D"urn:schemas-microsoft-com:office:word" = xmlns:m=3D"http://schemas.microsoft.com/office/2004/12/omml" = xmlns=3D"http://www.w3.org/TR/REC-html40"> <head> <meta http-equiv=3DContent-Type content=3D"text/html; = charset=3Dus-ascii"> <meta name=3DGenerator content=3D"Microsoft Word 12 (filtered medium)"> <!--[if !mso]> <style> v\:* {behavior:url(#default#VML);} o\:* {behavior:url(#default#VML);} w\:* {behavior:url(#default#VML);} .shape {behavior:url(#default#VML);} </style> <![endif]--> <style> <!-- /* Font Definitions */ @font-face {font-family:"Cambria Math"; panose-1:2 4 5 3 5 4 6 3 2 4;} @font-face {font-family:Calibri; panose-1:2 15 5 2 2 2 4 3 2 4;} @font-face {font-family:Tahoma; panose-1:2 11 6 4 3 5 4 4 2 4;} @font-face {font-family:Verdana; panose-1:2 11 6 4 3 5 4 4 2 4;} /* Style Definitions */ p.MsoNormal, li.MsoNormal, div.MsoNormal {margin:0in; margin-bottom:.0001pt; font-size:12.0pt; font-family:"Times New Roman","serif";} a:link, span.MsoHyperlink {mso-style-priority:99; color:blue; text-decoration:underline;} a:visited, span.MsoHyperlinkFollowed {mso-style-priority:99; color:purple; text-decoration:underline;} p {mso-style-priority:99; mso-margin-top-alt:auto; margin-right:0in; mso-margin-bottom-alt:auto; margin-left:0in; font-size:12.0pt; font-family:"Times New Roman","serif";} span.EmailStyle18 {mso-style-type:personal-reply; font-family:"Calibri","sans-serif"; color:#1F497D;} .MsoChpDefault {mso-style-type:export-only;} @page Section1 {size:8.5in 11.0in; margin:1.0in 1.0in 1.0in 1.0in;} div.Section1 {page:Section1;} --> </style> <!--[if gte mso 9]><xml> <o:shapedefaults v:ext=3D"edit" spidmax=3D"1026" /> </xml><![endif]--><!--[if gte mso 9]><xml> <o:shapelayout v:ext=3D"edit"> <o:idmap v:ext=3D"edit" data=3D"1" /> </o:shapelayout></xml><![endif]--> </head> <body lang=3DEN-US link=3Dblue vlink=3Dpurple> <div class=3DSection1> <p class=3DMsoNormal><span = style=3D'font-size:11.0pt;font-family:"Calibri","sans-serif"; color:#1F497D'>Tomi,<o:p></o:p></span></p> <p class=3DMsoNormal><span = style=3D'font-size:11.0pt;font-family:"Calibri","sans-serif"; color:#1F497D'><o:p> </o:p></span></p> <p class=3DMsoNormal><span = style=3D'font-size:11.0pt;font-family:"Calibri","sans-serif"; color:#1F497D'>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.<o:p></o:p></span></p> <p class=3DMsoNormal><span = style=3D'font-size:11.0pt;font-family:"Calibri","sans-serif"; color:#1F497D'><o:p> </o:p></span></p> <p class=3DMsoNormal><span = style=3D'font-size:11.0pt;font-family:"Calibri","sans-serif"; color:#1F497D'>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.<o:p></o:p></span></p> <p class=3DMsoNormal><span = style=3D'font-size:11.0pt;font-family:"Calibri","sans-serif"; color:#1F497D'><o:p> </o:p></span></p> <p class=3DMsoNormal><span = style=3D'font-size:11.0pt;font-family:"Calibri","sans-serif"; color:#1F497D'>[0] <a = href=3D"http://mashups.wso2.org/services/storexml?doc">http://mashups.wso= 2.org/services/storexml?doc</a><o:p></o:p></span></p> <p class=3DMsoNormal><span = style=3D'font-size:11.0pt;font-family:"Calibri","sans-serif"; color:#1F497D'>[1] <a href=3D"http://wso2.org/repos/wso2/trunk/commons/annotated-stylesheets/re= adme.htm">http://wso2.org/repos/wso2/trunk/commons/annotated-stylesheets/= readme.htm</a><o:p></o:p></span></p> <p class=3DMsoNormal><span = style=3D'font-size:11.0pt;font-family:"Calibri","sans-serif"; color:#1F497D'>[2] <a href=3D"http://mashups.wso2.org/services/LatestEarthquakes?wsdl2&anno= tation=3Dtrue">http://mashups.wso2.org/services/LatestEarthquakes?wsdl2&a= mp;annotation=3Dtrue</a><o:p></o:p></span></p> <p class=3DMsoNormal><span = style=3D'font-size:11.0pt;font-family:"Calibri","sans-serif"; color:#1F497D'>[3] <a href=3D"http://wso2.org/repos/wso2/trunk/commons/annotated-stylesheets/XM= LSchema.xsd">http://wso2.org/repos/wso2/trunk/commons/annotated-styleshee= ts/XMLSchema.xsd</a><o:p></o:p></span></p> <p class=3DMsoNormal><span = style=3D'font-size:11.0pt;font-family:"Calibri","sans-serif"; color:#1F497D'><o:p> </o:p></span></p> <p class=3DMsoNormal><b><span = style=3D'font-size:10.0pt;font-family:"Verdana","sans-serif"; color:#1F497D'>Jonathan Marsh</span></b><span style=3D'font-size:10.0pt; font-family:"Verdana","sans-serif";color:#80AE81'> - </span><span style=3D'color:#1F497D'><a href=3D"http://www.wso2.com"><span = style=3D'font-size: 10.0pt;font-family:"Verdana","sans-serif";color:#80AE81'>http://www.wso2.= com</span></a></span><span style=3D'font-size:10.0pt;font-family:"Verdana","sans-serif";color:#80AE8= 1'> - </span><span style=3D'color:#1F497D'><a = href=3D"http://auburnmarshes.spaces.live.com"><span style=3D'font-size:10.0pt;font-family:"Verdana","sans-serif";color:#80AE8= 1'>http://auburnmarshes.spaces.live.com</span></a><o:p></o:p></span></p> <p class=3DMsoNormal><span style=3D'color:#1F497D'> </span><span style=3D'font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497= D'><o:p></o:p></span></p> <div style=3D'border:none;border-left:solid blue 1.5pt;padding:0in 0in = 0in 4.0pt'> <div> <div style=3D'border:none;border-top:solid #B5C4DF 1.0pt;padding:3.0pt = 0in 0in 0in'> <p class=3DMsoNormal><b><span = style=3D'font-size:10.0pt;font-family:"Tahoma","sans-serif"'>From:</span>= </b><span style=3D'font-size:10.0pt;font-family:"Tahoma","sans-serif"'> = [email protected] [mailto:[email protected]] <b>On Behalf Of </b>Arthur Ryman<br> <b>Sent:</b> Friday, October 05, 2007 1:08 PM<br> <b>To:</b> tomi vanek<br> <b>Cc:</b> [email protected]; [email protected]<br> <b>Subject:</b> Re: documentation generated from = .wsdl<o:p></o:p></span></p> </div> </div> <p class=3DMsoNormal><o:p> </o:p></p> <p class=3DMsoNormal style=3D'margin-bottom:12.0pt'><br> <span = style=3D'font-size:10.0pt;font-family:"Arial","sans-serif"'>Tomi,</span> = <br> <br> <span style=3D'font-size:10.0pt;font-family:"Arial","sans-serif"'>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. </span><br> <br> <span = style=3D'font-size:10.0pt;font-family:"Arial","sans-serif"'>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.</span> <br> <br> <span style=3D'font-size:10.0pt;font-family:"Arial","sans-serif"'>[1] http://incubator.apache.org/woden/</span> <br> <span style=3D'font-size:10.0pt;font-family:"Arial","sans-serif"'>[2] http://dev.w3.org/cvsweb/2002/ws/desc/test-suite/interchange/</span> = <br> <br> <span style=3D'font-size:10.0pt;font-family:"Arial","sans-serif"'>Arthur = Ryman, PhD, AoT, DE<br> Process and Portfolio Management, Rational Division<br> <br> phone: +1-905-413-3077, TL 969-3077<br> assistant: +1-905-413-3831 (T/L: 318-8867)<br> fax: +1-905-413-4920, TL 969-4920<br> mobile: +1-416-939-5063, text: [email protected]</span> <br> <br> <o:p></o:p></p> <table class=3DMsoNormalTable border=3D0 cellpadding=3D0 width=3D"100%" style=3D'width:100.0%'> <tr> <td width=3D"40%" valign=3Dtop style=3D'width:40.0%;padding:.75pt = .75pt .75pt .75pt'> <p class=3DMsoNormal><b><span = style=3D'font-size:7.5pt;font-family:"Arial","sans-serif"'>tomi vanek <[email protected]></span></b><span = style=3D'font-size:7.5pt; font-family:"Arial","sans-serif"'> </span><br> <span style=3D'font-size:7.5pt;font-family:"Arial","sans-serif"'>Sent = by: [email protected]</span> <o:p></o:p></p> <p><span = style=3D'font-size:7.5pt;font-family:"Arial","sans-serif"'>10/04/2007 10:22 AM</span> <o:p></o:p></p> </td> <td width=3D"59%" valign=3Dtop style=3D'width:59.0%;padding:.75pt = .75pt .75pt .75pt'> <table class=3DMsoNormalTable border=3D0 cellpadding=3D0 = width=3D"100%" style=3D'width:100.0%'> <tr> <td valign=3Dtop style=3D'padding:.75pt .75pt .75pt .75pt'> <p class=3DMsoNormal align=3Dright style=3D'text-align:right'><span = style=3D'font-size:7.5pt;font-family:"Arial","sans-serif"'>To</span><o:p>= </o:p></p> </td> <td valign=3Dtop style=3D'padding:.75pt .75pt .75pt .75pt'> <p class=3DMsoNormal><span = style=3D'font-size:7.5pt;font-family:"Arial","sans-serif"'>www-ws-desc@w3= .org</span> <o:p></o:p></p> </td> </tr> <tr> <td valign=3Dtop style=3D'padding:.75pt .75pt .75pt .75pt'> <p class=3DMsoNormal align=3Dright style=3D'text-align:right'><span = style=3D'font-size:7.5pt;font-family:"Arial","sans-serif"'>cc</span><o:p>= </o:p></p> </td> <td valign=3Dtop style=3D'padding:.75pt .75pt .75pt .75pt'></td> </tr> <tr> <td valign=3Dtop style=3D'padding:.75pt .75pt .75pt .75pt'> <p class=3DMsoNormal align=3Dright style=3D'text-align:right'><span = style=3D'font-size:7.5pt;font-family:"Arial","sans-serif"'>Subject</span>= <o:p></o:p></p> </td> <td valign=3Dtop style=3D'padding:.75pt .75pt .75pt .75pt'> <p class=3DMsoNormal><span = style=3D'font-size:7.5pt;font-family:"Arial","sans-serif"'>Re: documentation generated from .wsdl</span><o:p></o:p></p> </td> </tr> </table> <p class=3DMsoNormal><o:p> </o:p></p> <table class=3DMsoNormalTable border=3D0 cellpadding=3D0> <tr> <td valign=3Dtop style=3D'padding:.75pt .75pt .75pt .75pt'></td> <td valign=3Dtop style=3D'padding:.75pt .75pt .75pt .75pt'></td> </tr> </table> </td> </tr> </table> <p class=3DMsoNormal><br> <br> <br> <b>Michael Potter-3 wrote:</b> <br> I have a need to document our webservices in a format usable by = non-technical users. <br> Maybe you could find useful my tool for WSDL documentation generation: = the <b>wsdl-viewer.xsl</b> (<a href=3D"http://tomi.vanek.sk/index.php?page=3Dwsdl-viewer" = target=3D"_top"><span style=3D'color:purple'>http://tomi.vanek.sk/index.php?page=3Dwsdl-viewer<= /span></a>). 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. <o:p></o:p></p> <div class=3DMsoNormal align=3Dcenter style=3D'text-align:center'> <hr size=3D2 width=3D"100%" align=3Dcenter> </div> <p class=3DMsoNormal>View this message in context: <a href=3D"http://www.nabble.com/documentation-generated-from-.wsdl-tf424575= 1.html#a13040893">Re: documentation generated from .wsdl</a><br> Sent from the <a = href=3D"http://www.nabble.com/w3.org---www-ws-desc-f11747.html">w3.org - www-ws-desc mailing list archive</a> at Nabble.com. <o:p></o:p></p> </div> </div> </body> </html> ------=_NextPart_000_008B_01C80A67.6E6A0410--