On Tue, Jun 10, 2008 at 10:06 AM, Martin Grotzke
<martin.grotzke_at_freiheit.com> wrote:
> Hi,
>
> I want to improve the generation of wadl so that resource and method
> comments are added to the related wadl-elements.
Yes please - regarding how the comments are wirtten, am I then the
only one who prefer a annotation style similar to the one used in
testng i.e:
--
@Test(description = "should assert that resource exists")
--
in JAX-RS this could be something like the following:
--
@Path("/users", description = "handle user interaction")
public class UserResource {
@POST(description = "create new user")
public Response createUser(User user) {
:
}
@GET(description = "get all users")
public List<User> getUsers() {
:
}
}
--
I know this requires API changes and does not allow for reuse of
JavaDoc comments, but most of the time I am much more verbose in my
JavaDoc comments anyway and also this has the benefit of being usable
in the auto generation of the WADL file.
Anyway any technique that will allow comments in the wadl is greatly
welcome, even if I have to run a seperate program to create them. By
the way it would be nice if with support for subresources in the wadl
documentation:
--
@Path("/users/config)
public ConfigResource getConfigResource() {
return new ConfigResource();
}
--
I have found that users (the programmers that uses my REST services)
have a hard time understanding that a single wadl document might not
be the entire picture. If such subresources was picket up by the
document generator then the user could browse it from there.
--
Yours sincerely
Lars Tackmann