Request Body Documentation for REST API Browser

[Malte Mohrmann]

Hi,

I'm having a javadoc problem and can't seem to find anything which addresses it.

I am trying to give an example for the request body of an API function which would be displayed in the REST API Browser, as is done for the Jira API

For example, this is the given request body for api/2/avatar/{type}/temporaryCrop from the Jira API

{

  "cropperWidth": 120,

  "cropperOffsetX": 50,

  "cropperOffsetY": 50,

  "needsCropping": false

}

After looking at the Jira source I can see how this is done, i.e. by using this line

* @request.representation.example

   * {@link com.atlassian.jira.rest.v2.issue.AvatarCroppingBean#DOC_EDIT_EXAMPLE}

and then instantiating the DOC_EDIT_EXAMPLE variable in the correct class.

I have done this for one of my functions but when i try to run atlas-debug the command stops when producing javadoc and gives me the following error:

Embedded error: An error has occurred in JavaDocs report generation: 
Exit code: 1 - javadoc: error - In doclet class com.sun.jersey.wadl.resourcedoc.ResourceDocletJSON,  method start has thrown an exception java.lang.reflect.InvocationTargetException
java.lang.VerifyError: (class: org/codehaus/jackson/map/ObjectMapper, method: writeValueAsBytes signature: (Ljava/lang/Object;)[B) Incompatible argument to function
	at org.codehaus.jackson.jaxrs.MapperConfigurator.mapper(MapperConfigurator.java:119)
	at org.codehaus.jackson.jaxrs.MapperConfigurator.configure(MapperConfigurator.java:94)
	at org.codehaus.jackson.jaxrs.JacksonJsonProvider.configure(JacksonJsonProvider.java:227)
	at com.atlassian.plugins.rest.common.json.JacksonJsonProviderFactory.create(JacksonJsonProviderFactory.java:14)
	at com.atlassian.plugins.rest.common.json.DefaultJaxbJsonMarshaller.marshal(DefaultJaxbJsonMarshaller.java:19)
	at com.sun.jersey.wadl.resourcedoc.ResourceDocletJSON.marshallBean(ResourceDocletJSON.java:573)
	at com.sun.jersey.wadl.resourcedoc.ResourceDocletJSON.getSerializedLinkFromTag(ResourceDocletJSON.java:558)
	at com.sun.jersey.wadl.resourcedoc.ResourceDocletJSON.getSerializedExample(ResourceDocletJSON.java:445)
	at com.sun.jersey.wadl.resourcedoc.ResourceDocletJSON.addRequestRepresentationDoc(ResourceDocletJSON.java:392)
	at com.sun.jersey.wadl.resourcedoc.ResourceDocletJSON.start(ResourceDocletJSON.java:184)
	at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
	at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
	at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
	at java.lang.reflect.Method.invoke(Method.java:597)
	at com.sun.tools.javadoc.DocletInvoker.invoke(DocletInvoker.java:269)
	at com.sun.tools.javadoc.DocletInvoker.start(DocletInvoker.java:143)
	at com.sun.tools.javadoc.Start.parseAndExecute(Start.java:340)
	at com.sun.tools.javadoc.Start.begin(Start.java:128)
	at com.sun.tools.javadoc.Main.execute(Main.java:41)
	at com.sun.tools.javadoc.Main.main(Main.java:31)

Command line was: /usr/lib/jvm/java-6-oracle/jre/../bin/javadoc -J-Xmx1024m @options @argfile

Refer to the generated Javadoc files in '/home/malte/work/git/tempo/teams/tempo-teams/target/site/apidocs' dir.

I feel like there might be something that i need to include in the pom.xml to get access to the ExtendedWODL which allows me to use the @request.representation.example but have been unsuccessful in my search for the past day and a half.

If anyone knows what this might be an answer would be much appreciated.

Thanks in advance

---

Malte

[Malte Mohrmann · Accepted solution]

Got an answer here:

https://ecosystem.atlassian.net/browse/AMPS-918