Update Documentation for Gradle Users in Resolving Models

In the current documentation/ReadMe.md, the documentation for @responseType has the following:

NOTE: if the response class is not in the same maven project as the one the doclet plugin is on then you will need to include the response class in the source of your project. One way to do this in maven is to use the maven-dependency-plugin's unpack goal to unpack the *.java files of the dependency source jar to a temporary directory such as ${project.build.directory}/additional-sources and then attach that directory to your project source using the build-helper-maven-plugin's add-source goal.

Unfortunately, my project is Gradle based. My gradle documentation task is mostly identical to the sample in the current documentation: https://github.com/teamcarma/swagger-jaxrs-doclet#gradle

However, I'm using @responseType with Model objects that are not in my project where the Doclet plugin is being run. Thus, I spent several hours trying to translate the above instructions into something that made sense with Gradle.

There are two solutions: Solution 1 For those not using Intelli-J, you can just define a sourceset that points to the source of your current project where the Doclet plugin is run + any Model projects:

sourceSets {
    doclet {
        java {
            srcDir 'src/main/java'
            // List all the source project directories where we define
            // Models that will be used by Doclet to generate REST API Docs
            srcDir project(":code:models:api").file("src/main/java")
        }
    }
}

Then update your task that generates the REST API Docs from:

source = sourceSets.main.allJava

to:

source = sourceSets.doclet.allJava

Solution 2 Unfortunately, if you are using Intelli-J, it's Gradle Sync/Plugin will complain if you define a SourceSet with sources outside of your project. See: https://youtrack.jetbrains.com/issue/IDEA-122577#tab=Comments

So instead, you have to "manually" build your source set:

task generateRestApiDocs(type: Javadoc) {
    // Ideally would use a custom-defined source set above
    // However, Intelli-J can't handle Sources out of content root
    // See: https://youtrack.jetbrains.com/issue/IDEA-122577#tab=Comments
    // and: https://github.com/spockframework/spock/issues/70
    // So instead "manually" creating the source set

    def sourceList = new ArrayList<File>()

    sourceList.addAll(sourceSets.main.allJava);
    project(":code:models:api").fileTree("src/main/java").each {
        sourceList.add(it)
    }

    source = sourceList
    options.classpath = configurations.doclet.files.asType(List)
    options.docletpath = configurations.doclet.files.asType(List)

   // ... Rest of doclet setup/configuration here

Posting this because it took me forever to figure all this out and figured it would be a nice add to the ReadMe.md.

teamcarma / swagger-jaxrs-doclet

Update Documentation for Gradle Users in Resolving Models #82