You are viewing a plain text version of this content. The canonical link for it is here.
Posted to users@cxf.apache.org by Pascal Leclercq <pa...@gmail.com> on 2014/02/06 14:47:25 UTC
Best way to publish WDSL / SOAP user friendly documentation.
Hi,
we do have quite a lot of Webservices and we would like to publish user
friendly infos on each of them.
So far, we use ServletController.generateServiceList() but It doesn't
display http://www.w3.org/TR/wsdl#_documentation in the WSDLs.
We could customize org.apache.cxf.transport.servlet.ServletController to
display more content (as suggested in an earlier thread) but before doing
so I would like to know if there is a better solution.
As alternative could be http://code.google.com/p/wsdl-viewer/ but the
project looks like pretty much dead...
Any suggestion would be pretty much appreciated.
Thanks
--
Pascal Leclercq
Re: Best way to publish WDSL / SOAP user friendly documentation.
Posted by Pascal Leclercq <pa...@gmail.com>.
Hi,
we used enunciate and I'm quite happy of what we get.
We use the maven plugin so we can generate html content during the build
process.
I can say It works very well now.
We also tried https://github.com/pavel-zeman/WSDLDoc with quite a lot of
success. It's simpler but so far there's no maven plugin.
Best regards.
2014-02-06 23:34 GMT+01:00 Pascal Leclercq <pa...@gmail.com>:
> Looks like exactly what I'm looking for...
>
> Will try and give feedback.
>
> Thanks !
>
>
> 2014-02-06 Winnebeck, Jason <Ja...@windstream.com>:
>
> I use http://enunciate.codehaus.org/ for this task with CXF. Enunciate
>> takes your Javadocs from classes and properties and builds a website as
>> well as a fully documented WSDL (SOAP), WADL (REST), and/or XSD as
>> appropriate. It also understands JAXB and Jackson annotations.
>>
>> Enunciate looks a little confusing because in its normal usage it
>> actually provides the servlet container and implementation for you, so you
>> don't need any web.xml or anything at all. But since I already had a CXF
>> app, you can have it just generate the (HTML) documentation and WSDL/XSD
>> with full documentation from the javadoc, which CXF/JAXB doesn't do. So in
>> my usage I have:
>>
>> API project containing just service interfaces and POJOs (with JAXB/XML
>> and Jackson/JSON annotations).
>> Enunciate generates HTML docs in a zip, WSDL, WADL, and XSD. These are
>> output artifacts from API project.
>> Server implementation project which makes war using CXF and depends on
>> API jar, WSDL, and WADL. WSDL/WADL provided to CXF as if I was doing
>> contract-first development. In this case CXF serves WSDL/WADL and replaces
>> the endpoint URLs to the proper ones discovered at runtime.
>> Docs are served by Apache in front of servlet container (but of course
>> servlet container could also serve static HTML just as easily).
>>
>> I won't lie, it was pretty hard for me to get set up, but once I did, I
>> am loving it because docs come from Javadoc so there is only one place for
>> documentation in the source and it ends up in 5 places: Javadocs, WSDL,
>> WADL, XSD, and HTML website.
>>
>> Jason
>>
>> -----Original Message-----
>> From: Pascal Leclercq [mailto:pascal.leclercq@gmail.com]
>> Sent: Thursday, February 06, 2014 8:47 AM
>> To: users@cxf.apache.org
>> Subject: Best way to publish WDSL / SOAP user friendly documentation.
>>
>> Hi,
>>
>> we do have quite a lot of Webservices and we would like to publish user
>> friendly infos on each of them.
>>
>>
>> So far, we use ServletController.generateServiceList() but It doesn't
>> display http://www.w3.org/TR/wsdl#_documentation in the WSDLs.
>>
>>
>> We could customize org.apache.cxf.transport.servlet.ServletController to
>> display more content (as suggested in an earlier thread) but before doing
>> so I would like to know if there is a better solution.
>>
>> As alternative could be http://code.google.com/p/wsdl-viewer/ but the
>> project looks like pretty much dead...
>>
>>
>> Any suggestion would be pretty much appreciated.
>>
>> Thanks
>>
>> --
>> Pascal Leclercq
>>
>> ----------------------------------------------------------------------
>> This email message and any attachments are for the sole use of the
>> intended recipient(s). Any unauthorized review, use, disclosure or
>> distribution is prohibited. If you are not the intended recipient, please
>> contact the sender by reply email and destroy all copies of the original
>> message and any attachments.
>>
>
>
>
> --
> Pascal Leclercq
>
>
--
Pascal Leclercq
Re: Best way to publish WDSL / SOAP user friendly documentation.
Posted by Pascal Leclercq <pa...@gmail.com>.
Looks like exactly what I'm looking for...
Will try and give feedback.
Thanks !
2014-02-06 Winnebeck, Jason <Ja...@windstream.com>:
> I use http://enunciate.codehaus.org/ for this task with CXF. Enunciate
> takes your Javadocs from classes and properties and builds a website as
> well as a fully documented WSDL (SOAP), WADL (REST), and/or XSD as
> appropriate. It also understands JAXB and Jackson annotations.
>
> Enunciate looks a little confusing because in its normal usage it actually
> provides the servlet container and implementation for you, so you don't
> need any web.xml or anything at all. But since I already had a CXF app, you
> can have it just generate the (HTML) documentation and WSDL/XSD with full
> documentation from the javadoc, which CXF/JAXB doesn't do. So in my usage I
> have:
>
> API project containing just service interfaces and POJOs (with JAXB/XML
> and Jackson/JSON annotations).
> Enunciate generates HTML docs in a zip, WSDL, WADL, and XSD. These are
> output artifacts from API project.
> Server implementation project which makes war using CXF and depends on API
> jar, WSDL, and WADL. WSDL/WADL provided to CXF as if I was doing
> contract-first development. In this case CXF serves WSDL/WADL and replaces
> the endpoint URLs to the proper ones discovered at runtime.
> Docs are served by Apache in front of servlet container (but of course
> servlet container could also serve static HTML just as easily).
>
> I won't lie, it was pretty hard for me to get set up, but once I did, I am
> loving it because docs come from Javadoc so there is only one place for
> documentation in the source and it ends up in 5 places: Javadocs, WSDL,
> WADL, XSD, and HTML website.
>
> Jason
>
> -----Original Message-----
> From: Pascal Leclercq [mailto:pascal.leclercq@gmail.com]
> Sent: Thursday, February 06, 2014 8:47 AM
> To: users@cxf.apache.org
> Subject: Best way to publish WDSL / SOAP user friendly documentation.
>
> Hi,
>
> we do have quite a lot of Webservices and we would like to publish user
> friendly infos on each of them.
>
>
> So far, we use ServletController.generateServiceList() but It doesn't
> display http://www.w3.org/TR/wsdl#_documentation in the WSDLs.
>
>
> We could customize org.apache.cxf.transport.servlet.ServletController to
> display more content (as suggested in an earlier thread) but before doing
> so I would like to know if there is a better solution.
>
> As alternative could be http://code.google.com/p/wsdl-viewer/ but the
> project looks like pretty much dead...
>
>
> Any suggestion would be pretty much appreciated.
>
> Thanks
>
> --
> Pascal Leclercq
>
> ----------------------------------------------------------------------
> This email message and any attachments are for the sole use of the
> intended recipient(s). Any unauthorized review, use, disclosure or
> distribution is prohibited. If you are not the intended recipient, please
> contact the sender by reply email and destroy all copies of the original
> message and any attachments.
>
--
Pascal Leclercq
RE: Best way to publish WDSL / SOAP user friendly documentation.
Posted by "Winnebeck, Jason" <Ja...@windstream.com>.
I use http://enunciate.codehaus.org/ for this task with CXF. Enunciate takes your Javadocs from classes and properties and builds a website as well as a fully documented WSDL (SOAP), WADL (REST), and/or XSD as appropriate. It also understands JAXB and Jackson annotations.
Enunciate looks a little confusing because in its normal usage it actually provides the servlet container and implementation for you, so you don't need any web.xml or anything at all. But since I already had a CXF app, you can have it just generate the (HTML) documentation and WSDL/XSD with full documentation from the javadoc, which CXF/JAXB doesn't do. So in my usage I have:
API project containing just service interfaces and POJOs (with JAXB/XML and Jackson/JSON annotations).
Enunciate generates HTML docs in a zip, WSDL, WADL, and XSD. These are output artifacts from API project.
Server implementation project which makes war using CXF and depends on API jar, WSDL, and WADL. WSDL/WADL provided to CXF as if I was doing contract-first development. In this case CXF serves WSDL/WADL and replaces the endpoint URLs to the proper ones discovered at runtime.
Docs are served by Apache in front of servlet container (but of course servlet container could also serve static HTML just as easily).
I won't lie, it was pretty hard for me to get set up, but once I did, I am loving it because docs come from Javadoc so there is only one place for documentation in the source and it ends up in 5 places: Javadocs, WSDL, WADL, XSD, and HTML website.
Jason
-----Original Message-----
From: Pascal Leclercq [mailto:pascal.leclercq@gmail.com]
Sent: Thursday, February 06, 2014 8:47 AM
To: users@cxf.apache.org
Subject: Best way to publish WDSL / SOAP user friendly documentation.
Hi,
we do have quite a lot of Webservices and we would like to publish user friendly infos on each of them.
So far, we use ServletController.generateServiceList() but It doesn't display http://www.w3.org/TR/wsdl#_documentation in the WSDLs.
We could customize org.apache.cxf.transport.servlet.ServletController to display more content (as suggested in an earlier thread) but before doing so I would like to know if there is a better solution.
As alternative could be http://code.google.com/p/wsdl-viewer/ but the project looks like pretty much dead...
Any suggestion would be pretty much appreciated.
Thanks
--
Pascal Leclercq
----------------------------------------------------------------------
This email message and any attachments are for the sole use of the intended recipient(s). Any unauthorized review, use, disclosure or distribution is prohibited. If you are not the intended recipient, please contact the sender by reply email and destroy all copies of the original message and any attachments.
Re: Best way to publish WDSL / SOAP user friendly documentation.
Posted by Pascal Leclercq <pa...@gmail.com>.
Hi,
no we use WSDL first Web Services.
I suspect @WSDLDocumentation to have somehow the same effect as
http://www.w3.org/TR/wsdl#_documentation.
We would like to display this documentation with the WSDL in a user
friendly format. Pretty much lika a javadoc would do for java Code.
Pascal
2014-02-06 Daniel Kulp <dk...@apache.org>:
>
> On Feb 6, 2014, at 8:47 AM, Pascal Leclercq <pa...@gmail.com>
> wrote:
>
> > Hi,
> >
> > we do have quite a lot of Webservices and we would like to publish user
> > friendly infos on each of them.
>
> Is this a java first use case so that the wsdl is generated by CXF? If
> so, you should try using the @WSDLDocumentation annotations that CXF
> provides:
>
> http://cxf.apache.org/docs/annotations.html
>
> They can be used to enhance the WSDL’s with extra documentation nodes that
> some tools can pick up and display to the users.
>
> Dan
>
>
> >
> >
> > So far, we use ServletController.generateServiceList() but It doesn't
> > display http://www.w3.org/TR/wsdl#_documentation in the WSDLs.
> >
> >
> > We could customize org.apache.cxf.transport.servlet.ServletController to
> > display more content (as suggested in an earlier thread) but before doing
> > so I would like to know if there is a better solution.
> >
> > As alternative could be http://code.google.com/p/wsdl-viewer/ but the
> > project looks like pretty much dead...
> >
> >
> > Any suggestion would be pretty much appreciated.
> >
> > Thanks
> >
> > --
> > Pascal Leclercq
>
> --
> Daniel Kulp
> dkulp@apache.org - http://dankulp.com/blog
> Talend Community Coder - http://coders.talend.com
>
>
--
Pascal Leclercq
Re: Best way to publish WDSL / SOAP user friendly documentation.
Posted by Daniel Kulp <dk...@apache.org>.
On Feb 6, 2014, at 8:47 AM, Pascal Leclercq <pa...@gmail.com> wrote:
> Hi,
>
> we do have quite a lot of Webservices and we would like to publish user
> friendly infos on each of them.
Is this a java first use case so that the wsdl is generated by CXF? If so, you should try using the @WSDLDocumentation annotations that CXF provides:
http://cxf.apache.org/docs/annotations.html
They can be used to enhance the WSDL’s with extra documentation nodes that some tools can pick up and display to the users.
Dan
>
>
> So far, we use ServletController.generateServiceList() but It doesn't
> display http://www.w3.org/TR/wsdl#_documentation in the WSDLs.
>
>
> We could customize org.apache.cxf.transport.servlet.ServletController to
> display more content (as suggested in an earlier thread) but before doing
> so I would like to know if there is a better solution.
>
> As alternative could be http://code.google.com/p/wsdl-viewer/ but the
> project looks like pretty much dead...
>
>
> Any suggestion would be pretty much appreciated.
>
> Thanks
>
> --
> Pascal Leclercq
--
Daniel Kulp
dkulp@apache.org - http://dankulp.com/blog
Talend Community Coder - http://coders.talend.com
RE: Best way to publish WDSL / SOAP user friendly documentation.
Posted by "Hart, Andrew B." <AH...@Akimeka.com>.
XMLSpy can generate documentation from a WSDL.
http://www.altova.com/xmlspy.html
-----Original Message-----
From: Pascal Leclercq [mailto:pascal.leclercq@gmail.com]
Sent: Thursday, February 06, 2014 7:47 AM
To: users@cxf.apache.org
Subject: Best way to publish WDSL / SOAP user friendly documentation.
Hi,
we do have quite a lot of Webservices and we would like to publish user friendly infos on each of them.
So far, we use ServletController.generateServiceList() but It doesn't display http://www.w3.org/TR/wsdl#_documentation in the WSDLs.
We could customize org.apache.cxf.transport.servlet.ServletController to display more content (as suggested in an earlier thread) but before doing so I would like to know if there is a better solution.
As alternative could be http://code.google.com/p/wsdl-viewer/ but the project looks like pretty much dead...
Any suggestion would be pretty much appreciated.
Thanks
--
Pascal Leclercq