@returnWrapped does not work for model classes

[msamusenka]

I have a model class where I would like to substitute the return type of a property with @returnWrapped JavaDoc tag. This is not working.

public class PointDto {
    private Instant timestamp;

    /**
     * X coordinate (timestamp).
     * @returnWrapped               java.lang.String
     * @documentationExample        2017-04-13T13:10:06Z
     */
    public Instant getTimestamp() {
        return timestamp;
    }
}

At the same time @TypeHint annotation works as expected:

public class PointDto {
    private Instant timestamp;

    /**
     * X coordinate (timestamp).
     * @documentationExample        2017-04-13T13:10:06Z
     */
    @TypeHint(String.class)
    public Instant getTimestamp() {
        return timestamp;
    }
}

[stoicflame]

Yes, @returnWrapped is specifically designated for JAX-RS API.

Why not use the standard Jackson/JAXB annotations for specifying type?

[msamusenka]

Let me describe my aims. I'am using (or trying to use) JavaDoc tags insead of enunciate annotations just to remove an unnecessary compile-time external dependency, since the runtime of my project does not actually depend on those annotations. All the enunciate-specific logic is performed during build phase.

The other important reason is to keep the code cleaner from specific annotations. Because at some point you find your controllers and models decorated with a lot of annotations. Some of them (Spring-related or Jackson-related) are important for runtime, while some are not. Less annotations are easier to read, easier to understand, easier to maintain and easier to involve new developers into the project. So from my perspective custom tags are much more preferable than annotations and if it is possible I would like to stick with them.

Why not use the standard Jackson/JAXB annotations for specifying type?

From my understanding Jackson does not offer any annotaions that allow you type remapping. @JsonTypeName was designed to address polymorphism, not the type remapping. Anyway, the decision how to serialize my Instant is performed by the ObjectMapper depending on its configuration. It would be strange to hard-code this in the model itself.

So, summarizing said above, it would be extremely useful (at least for me personally) if enunciate JavaDoc tags would be functionally equivalent to enunciate annotations.

[stoicflame]

I've looked into the work to support this, and it's pretty significant. It's not going to fit into 2.10.

[stoicflame]

This enhancement is currently seeking a sponsor. If anybody is willing to sponsor the work, reach out to me and I'd be happy to pick it up.