FroMage
Custom text in HTTP Example section
Reported by [email protected], Jun 7, 2011 A nice feature will be possibility to put custom text in 'HTTP Example' section so I can provide my own example HTTP request and example HTTP response (even more than once). Some new annotations will be required i.e. @exampleRequest and @exampleResponse.
What do you think?
Comment 1 by project member stephane.epardaud, Jul 18, 2011 @include is not enough for you?
See http://www.lunatech-labs.com/files/jax-doclets/docs/0.9.0/html/index.html#d0e439
Comment 2 by [email protected], Jul 28, 2011 Its helpful if the XML represents a domain data. I would prefer a method in the class which returns a String. Annotated with @ExampleRequest(Type=*.Class)
Comment 3 by [email protected], Jul 30, 2011 @include is not enough because often response (json response) is map to some general object like JSONObject or JSONArray and it pointless to create dedicated class to use it only in @include.
Comment 4 by project member stephane.epardaud, Aug 15, 2011 #2: I'm strongly against calling a method to get documentation. JavaDoc comments are meant for that. Though I agree domain data is good, I'm just not sure @include isn't enough.
#3: I suppose I can agree that @exampleRequest and @exampleResponse are valid alternatives to @include in order to inline the examples, if you don't want them in separate files.
+1 vote for this. I wrote a service that allows arbitrary data to flow through it with a loose structure so everything is returned as simple JSONObjects. Currently, I'm using:
@returnWrapped Example <pre>...</pre>
And:
...[in general method Javadoc]... Example input: <pre>...</pre> ... @inputWrapped (see above)
Which is kludgy.
Ideally, something like @exampleRequest and @exampeResponse to just do free-form examples would be perfect.
Bonus if you can do multiple @exampleRequest/@exampleResponse pairings. Perhaps something like @exampleRequest(1, "request 1 desc.")/@exampleResponse(1, "response 1 desc.") and then @exampleRequest(2, "request 2 desc.")/@exampleResponse(2, "response 2 desc.") would be nice.
