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
>>
>>
>
--
| ? + ? = To question
----------------\
Paul Sandoz
x38109
+33-4-76188109