Multi-module maven project doesn't get documented with jackson

[patvong]

I have a multi module project and I followed this wiki https://github.com/stoicflame/enunciate/wiki/Multi-Module-Projects to make sure all the source jars are created for each modules.
I noticed that I need to use the @JsonProperty so that Enunciate can pick up the fields/properties of my data type classes.
However, for some reason, if I add this configuration:

<sourcepath-excludes>
          <exclude>
            <groupId>com.mycompany</groupId>
          </exclude>
</sourcepath-excludes>

Enunciate will pick up all the fields from all modules, but it will not generate the documentation that I added on the class or on the fields/properties.

[stoicflame]

So is the problem that you need to add @JsonProperty or is it that the documentation is missing?

[patvong]

1. The field were all present, but the documentation was missing
2. I added

<sourcepath-excludes>
          <exclude>
            <groupId>com.mycompany</groupId>
          </exclude>
</sourcepath-excludes>

Then some documentation was present e.g. the class documentation, but not the field documentation. To be able to view the fields and their documentation I had to add @JsonProperty.

[patvong]

@stoicflame Sorry for the long post ahead.

After further investigation, it seems related to the usage of Lombok's annotations.
I have this class annotated with lombok, except for the activated field where I manually create the getter and setter. The class is in a module A.

/**
 * Represents an active/inactive user
 */
@JsonIgnoreProperties(ignoreUnknown = true)
@Data @EqualsAndHashCode(callSuper = true) @NoArgsConstructor @AllArgsConstructor @Builder
public class InactiveUserWS extends ResourceSupport implements Serializable {
    private static final long serialVersionUID = 8510292065307561800L;

    /**
     *  User email
     */
    private String email;

    /**
     *  User password
     */
    private String password;

    /**
     * Is user activated
     */
    private boolean activated;

    /**
     * Is user activated: GETTER
     */
    public boolean isActivated() {
        return activated;
    }

    public void setActivated(boolean v) {
        this.activated = v;
    }
}

1. Excluded sources

I have another module B that includes module A with the class InactiveUserWS. From module B I run enunciate. This is what Enunciate will generate me if I exclude the source in the enunciate-maven-plugin configuration:

<sourcepath-excludes>
   <exclude>
      <groupId>com.appdirect</groupId>
   </exclude>
</sourcepath-excludes>

Notice that the fields are detected, but not the documentation. Also the class documentation is not present.

From my module B, I have a class annotatated with lombok only and Enunciate would not detect any fields:

/**
 * Developper information
 */
@Getter
@Setter
@NoArgsConstructor
public class DeveloperAppWS implements Serializable {
    private static final long serialVersionUID = 6648244950449963420L;

    /**
     * Developer id
     */
    private Long id;
    private Date lastModified;
    private String name;
    private ApplicationStatus status;
}

2. Sources not excluded

Then I remove the previous exclusion from the enunciate-maven-plugin configuration:

<sourcepath-excludes>
   <exclude>
      <groupId>com.appdirect</groupId>
   </exclude>
</sourcepath-excludes>

This is what I get from Enunciate:

Notice that only the activated field was documented. The class documentation is present too.

That brings me to believe that when Enunciate looks at the source jar that contains my class it won't see the getter and setter provided by lombok thus eliminates the field from the documentation. I think that's fair and I might consider using https://projectlombok.org/features/delombok.html to package a source jar with the getter/setters from lombok.

However, I don't understand how in the first case Enunciate was able to get all the fields?

3. Usage of JAXB annotations

Now if I add the class annotations:

@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)

and I set honorJaxb="true" in my config, Enunciate will generate the documentation as expected:

Note that the documentation will be taken from the field and not from the getter for the activated field.
It seems that if those annotations are present, Enunciate will scan through all the fields, even if they are private.
Is it possible to have this kind of support for Jackson?

Takeaway

The fields will not be present if:

• the class is only annotated with lombok (due to missing source for getter/setter not available to Enunciate)
• the class lives in another module

The documentation will not be generated if:

• The class is only annotated with lombok

The documentation will be generated if

• the JAXB annotations are present
• or the getter/setters are created manually and are public: enunciate will take the getter documentation
• or the field is public

Possible solution/workaround

• Support something similar to @XmlRootElement and @XmlAccessorType(XmlAccessType.FIELD) for Jackson (preferred solution)
• Add the JAXB annotations in my JSON classes (workaround for now)
• Possibility to detect the @getter and @Setter lombok annotation on the class? If yes, then Enunciate should document all the fields even if private? (less preferred solution)
• Use delombok (less preferred workaround)
• Use @JsonProperty on every field (less preferred workaround)
• Other ideas?

[patvong]

I found out I could use @JsonAutoDetect(getterVisibility = JsonAutoDetect.Visibility.ANY, fieldVisibility = JsonAutoDetect.Visibility.ANY) to achieve the same result as honorJaxb=true and @XmlRootElement @XmlAccessorType(XmlAccessType.FIELD).

However I can't find a way to arbitrary ignore a field?
@Ignore and @Facet("ignore") won't work on fields. Any tips?
Edit: Got it to work, i was adding the <facets> element in the wrong place in the enunciate config: it must be right after <api-classes>.

[stoicflame]

@JsonIgnore

See Jackson-Annotations.

[stoicflame]

@patvong, thanks for the thread and the details. After reading through your observations above, I think you came to the right solution to use @JsonAutoDetect to specify the field visibility. Since Enunciate supports this annotation, I'm going to consider this issue closed. I'd be happy to re-open as needed.

[stoicflame]

Enunciate 2.3 has been released.