Hi,
I just merged the maven-wadl-plugin to the trunk [1]. This can be used
to generate an application.wadl that is extended with information read
from javadoc tags.
You can even process your custom tags, for this you must implement a
DocProcessor and a WadlGenerator.
A sample application can be found at samples/generate-wadl [2], this
provides an example for all features provided (including DocProcessor
and WadlGenerator).
The sample application contains a very simple README that provides a
description of the relevant artifacts [3].
TODOs:
- The WadlMethodFactory (OPTIONS support) does not use the
resourcedoc
- Jersey must allow to specify these wadl-hooks so that these can also
be used at runtime. Right now I have s.th. like a WadlGeneratorConfig
in mind, a class that provides the required configuration.
Feedback welcome, if you have any questions please ask :)
Cheers,
Martin
[1]
https://jersey.dev.java.net/source/browse/jersey/trunk/jersey/contribs/maven-wadl-plugin
[2]
https://jersey.dev.java.net/source/browse/jersey/trunk/jersey/samples/generate-wadl/
[3]
https://jersey.dev.java.net/source/browse/jersey/trunk/jersey/samples/generate-wadl/README
On Wed, 2008-06-18 at 11:32 +0200, Paul Sandoz wrote:
> Very nice!
>
> As soon as we switch over to 0.9 for the trunk we should merge it back
> to make it easier for people to give it a test drive.
>
> I think it might be very useful to include a documented example as part
> of the distribution.
>
> Paul.
>
> Martin Grotzke wrote:
> > Hi,
> >
> > now I have a first working version committed in the branch [1]. What is
> > included:
> >
> > - Added a maven-wadlplugin that provides a doclet that generates
> > a so called resourcedoc: some xml file containing javadoc and more
> > meta information (like xsd-element references) about your resource
> > classes
> > - The maven-wadl-plugin also can generate a wadl file that reads the
> > resourcedoc.xml and uses this meta information to create doc and other
> > elements in the wadl file
> > - The jersey WadlResource tries to read a resourcedoc.xml from the
> > classpath and in this case also creates a wadl file including
> > documentation/comments (-> request
> > http://localhost/api/application.wadl to retrieve the wadl resource).
> > * There's just one issue: The UriInfo seems not to be initialized,
> > therefore the baseUri might not be initialized
> >
> > An example of additionally supported javadoc tags that can be used:
> >
> > /**
> > * Creates a new User.
> > *
> > * @param createUserRequest the entity with user data
> > *
> > * @request.representation.qname {http://www.example.com/api}createUserRequest
> > * @request.representation.example {_at_link Examples#CREATE_USER_REQUEST_EXAMPLE}
> > *
> > * @response.param {_at_name Location}
> > * {_at_style header}
> > * {@type {http://www.w3.org/2001/XMLSchema}anyURI}
> > * {_at_doc The URI where the user has been created.}
> > *
> > * @response.representation.500.qname {http://www.example.com/api}error
> > * @response.representation.500.mediaType application/xml
> > * @response.representation.500.example {_at_link Examples#ERROR_EXAMPLE}
> > *
> > * @response.representation.400.qname {http://www.example.com/api}messages
> > * @response.representation.400.mediaType application/xml
> > * @response.representation.400.example {_at_link Examples#MESSAGES_EXAMPLE}
> > *
> > * @response.representation.201.qname {http://www.example.com/api}user
> > * @response.representation.201.mediaType application/xml
> > * @response.representation.201.example {_at_link Examples#GET_USER_EXAMPLE}
> > *
> > * @return Returns the user that has been created.
> > */
> > @POST
> > @ConsumeMime( { "application/xml" } )
> > @ProduceMime({ "application/xml" })
> > public Response createUser( CreateUserRequest createUserRequest ) {
> > ...
> > }
> >
> > The representation.qname {http://www.example.com/api}createUserRequest
> > sets the element attribute of a representation. What's missing right
> > now, is the specification of grammars for the WADL (see below for more
> > TODOs).
> >
> > The {_at_link Examples#CREATE_USER_REQUEST_EXAMPLE} is followed, read and
> > marshalled to xml, that is added as a <doc /> element to the
> > representation. All other things should be self descriptive.
> >
> >
> > An example how to configure it's own (app) pom.xml:
> >
> > <plugin>
> > <groupId>org.apache.maven.plugins</groupId>
> > <artifactId>maven-javadoc-plugin</artifactId>
> > <configuration>
> >
> > <encoding>UTF-8</encoding>
> > <verbose>false</verbose>
> > <show>public</show>
> > <subpackages>path.to.resources</subpackages>
> >
> > <doclet>com.sun.jersey.wadl.resourcedoc.ResourceDoclet</doclet>
> > <docletArtifacts>
> > <docletArtifact>
> > <groupId>com.sun.jersey</groupId>
> > <artifactId>maven-wadl-plugin</artifactId>
> > <version>0.8-ea-SNAPSHOT</version>
> > </docletArtifact>
> > <!--
> > Also specify jersey as doclet artifact as the ResourceDoclet
> > uses classes provided by jersey to generate the resourcedoc.
> > -->
> > <docletArtifact>
> > <groupId>com.sun.jersey</groupId>
> > <artifactId>jersey</artifactId>
> > <version>0.8-ea-SNAPSHOT</version>
> > </docletArtifact>
> > </docletArtifacts>
> > <!--
> > The resourcedoc.xml is also read by the WadlResource.java that
> > provides the application.wadl for your jersey app. So this should
> > not be changed
> > -->
> > <additionalparam>-output ${project.build.outputDirectory}/resourcedoc.xml</additionalparam>
> >
> > </configuration>
> > </plugin>
> >
> > <plugin>
> > <groupId>com.sun.jersey</groupId>
> > <artifactId>maven-wadl-plugin</artifactId>
> > <version>0.8-ea-SNAPSHOT</version>
> > <executions>
> > <execution>
> > <id>generate-wadl</id>
> > <goals>
> > <goal>generate</goal>
> > </goals>
> > </execution>
> > </executions>
> >
> > <configuration>
> >
> > <resourceDocFile>
> > ${project.build.outputDirectory}/resourcedoc.xml
> > </resourceDocFile>
> >
> > <wadlFile>${project.build.outputDirectory}/application.wadl</wadlFile>
> > <baseUri>http://www.example.com/api</baseUri>
> > <packagesResourceConfig>
> > <param>path.to.resources</param>
> > </packagesResourceConfig>
> > <dependencies>
> > <!--
> > Additional dependencies for resolving ClassNotFoundExceptons
> > can be added here
> > -->
> > <dependency>
> > <groupId>commons-codec</groupId>
> > <artifactId>commons-codec</artifactId>
> > <version>1.3</version>
> > </dependency>
> > </dependencies>
> > </configuration>
> > </plugin>
> >
> >
> > To generate just the resourcedoc.xml run
> > # mvn javadoc:javadoc
> >
> > To generate the wadl using the resourcedoc run
> > # mvn javadoc:javadoc com.sun.jersey:maven-wadl-plugin:generate
> >
> >
> > TODOs:
> > - The WadlMethodFactory (OPTIONS support) does not use the
> > resourcedoc
> > - The grammars must be set on the generated wadl so that referenced
> > xsd-elements can be resolved
> > - The ResourceDoclet must allow to hook into the resourcedoc generation,
> > so that users can read their specific javadoc tags (like e.g.
> > @security.ssl)
> > - The maven-wadl-plugin (GenerateWadlMojo) must allow to hook into the
> > wadl generation, so that application specific information can be used
> > to pimp the generated wadl
> > - Jersey must allow to specify these wadl-hooks so that these can also
> > be used at runtime
> >
> >
> > This was the first start, feedback welcome. If you want to test this
> > stuff you have to switch to the branch [1] and build jersey by yourself
> > (e.g. change the artifact version to some 0.8-wadl-SNAPSHOT).
> >
> >
> > Cheers,
> > Martin
> >
> >
> > [1] https://jersey.dev.java.net/svn/jersey/branches/wadl-generator-improvements
> >
> >
> > On Tue, 2008-06-10 at 10:06 +0200, Martin Grotzke wrote:
> >> Hi,
> >>
> >> I want to improve the generation of wadl so that resource and method
> >> comments are added to the related wadl-elements.
> >>
> >> The idea is basically that of Seth Call: Create some xml-representation
> >> of the javadoc so that this information can be read when the wadl is
> >> generated.
> >>
> >> Additionally we want to be able to add examples for representations, so
> >> that it's easy for readers of the doc to get an idea of in/out data.
> >> My idea is to create a taglet like "@request.representation.example".
> >> Are there any suggestions / other requirements concerning this that I
> >> should/could take into consideration?
> >>
> >> Also we want to reference schema elements in our representations.
> >>
> >> I would prefer do improve the existing jersey WadlGenerator that writing
> >> our own.
> >> @jersey-devs: Is this also s.th. that you would prefer?
> >>
> >> I would start with a maven-plugin so that testing cycles are as short as
> >> possible. Then I would create the taglets/doclets, create the required
> >> javadoc-xml file and afterwards extend the WadlGenerator.
> >>
> >> Shall changes be done in the trunk, or would you prefer to keep this in
> >> a branch?
> >>
> >> Cheers,
> >> Martin
> >>
> >>
> >