Tuesday, 10 September 2013

How can I generate documentation for my Jersey REST API that uses JSON JAXB binding?

How can I generate documentation for my Jersey REST API that uses JSON
JAXB binding?

Now that I've figured out how to use JAXB generate JSON I can
request/respond with it on my server and I'd like to figure out how I can
generate useful documentation for human beings that are not using Java. My
server code looks like this:
@POST
@Path("apath")
@Consumes(MediaType.APPLICATION_JSON)
public String postAPath(InstanceWithXmlRootElementAnnotation
instanceWithXmlRootElementAnnotation) {
That's all well in good if someone is using Java. I just give them the Jar
with the InstanceWithXmlRootElementAnnotation class in it and tell them to
send it over (yes, there's a little more work, ignore those details).
If they're using some other language, I don't know how I'm supposed to
tell them the format of their payload and what to expect from the server
if it returns a InstanceWithXmlRootElementAnnotation. How can I generate
documentation that explains the expected format of the JSON payload?

No comments:

Post a Comment