versly/wsdoc — pull request #24 by balthorium (2014-05-29 19:34:19+00:00)
Title: Add support for emitting raml markup

This is actually not yet ready for a pull request, but wanted to get feedback on the approach so far.

What I like about this changeset is that it works, I can generate workable RAML from wsdoc and use the results in RAML presentation tools (API Console, raml2html, etc.). It uses Jackson jsonSchema module to produce json-schema describing request and response DTO's, and keys on the Jackson @JsonPropertyDescription annotation for description on each property.

There are some downsides, though:

(1) The combination of annotations processing and reflection based processing is an odd mix. Using the jsonSchema module adds a dependency that the class be pre-compiled and on the processor's classpath.

(2) The jsonSchema module required a patch to make it process the @JsonPropertyDescription annotation correctly, so being able to take advantage of that depends on a pull request I submitted for that.

(3) The jsonSchema module seems emotionally unequipped to deal with recursive DTO's. I think I can fix that, but then there's another dependency on a pull request to jsonSchema.

Ideally I'd like to use jsonSchema and just fix whatever issues I run into as I go, but if folks are uncomfortable with the implications of the above issues I could alternatively rip it out and try to generate json-schema directly from the wsdoc metadata. Thoughts?