Property Visibility

Property Visibility

Enunciate looks for annotations (including Enunciate Specific Annotations) and JavaDoc on the code elements that are to be used by the underlying runtime engine.

Enunciate users often get confused (#281, #317, #367, #395, #431, #578, #715) when Enunciate doesn't pick up their annotations or JavaDoc that are being applied to an irrelevant code element. Consider the following class:

public class Person {

  /**
   * The name of the person.
   */
  @Size(max=50, min=2)
  private String name;

  public String getName() {
    return this.name;
  }

  public void setName(String name) {
    this.name = name;
  }
}

In the case above, the @Size annotation might be honored by the validation engine, but Enunciate probably won't be able to "see" it because the annotation is applied to the field, but the property (getter) is the element that will be used by the serialization engine (e.g. Jackson, JAXB) to serialize the instance. For the same reason, the JavaDoc ("The name of the person.") won't be "seen" by Enunciate.

In such a case, the annotation/JavaDoc either needs to be moved to the property (getter or setter), or the serialization engine needs to be told to use the field. This can be done by applying the relevant serialization annotation (e.g. @JsonProperty, @XmlElement) or by applying a more global annotation (e.g. @JsonAutoDetect, @XmlAccessorType).

If the class is annotated with Lombok annotations such as @Data, @Getters, and/or @Setters, adding the enunciate-lombok dependency as described in the Lombok FAQ page would allow the JavaDocs applied to fields be "seen" by Enunciate.