Feature/#13 support for jdk9 - controller doc - gradle example - refactoring

[ghilainm]

The following changes have been performed:

• Added support for Gradle
• Added support for JDK9+ doclet API
• Improvement of code structure
• Added example with Gradle
• Added support for Javadoc on the Controller (New Feature > Support documentation of API via Javadoc #16)
• Improvement of documentation
• Removal of duplicate build process for clarity
• Migrate to new version of Gradle
• Migrate code to Java9+
• Migrate to newer version of Spring

[ghilainm]

@dilipkrish Any time when you think you can review this?

[ghilainm]

@dilipkrish any news?

[soberich]

@ghilainm
Hi,
From you branch I am having

javadoc: error - fatal error encountered: java.lang.NullPointerException
javadoc: error - Please file a bug against the javadoc tool via the Java bug reporting page
(http://bugreport.java.com) after checking the Bug Database (http://bugs.java.com)
for duplicates. Include error messages and the following diagnostic in your report. Thank you.
java.lang.NullPointerException
	at springfox.javadoc.doclet.SwaggerPropertiesDoclet.processMethod(SwaggerPropertiesDoclet.java:198)
	at springfox.javadoc.doclet.SwaggerPropertiesDoclet.lambda$storeClassMethodAsProperties$4(SwaggerPropertiesDoclet.java:171)
	at java.base/java.util.stream.ForEachOps$ForEachOp$OfRef.accept(ForEachOps.java:183)
	at java.base/java.util.stream.ReferencePipeline$2$1.accept(ReferencePipeline.java:177)
	at java.base/java.util.Iterator.forEachRemaining(Iterator.java:133)
	at java.base/java.util.Spliterators$IteratorSpliterator.forEachRemaining(Spliterators.java:1801)
	at java.base/java.util.stream.AbstractPipeline.copyInto(AbstractPipeline.java:484)
	at java.base/java.util.stream.AbstractPipeline.wrapAndCopyInto(AbstractPipeline.java:474)
	at java.base/java.util.stream.ForEachOps$ForEachOp.evaluateSequential(ForEachOps.java:150)
	at java.base/java.util.stream.ForEachOps$ForEachOp$OfRef.evaluateSequential(ForEachOps.java:173)
	at java.base/java.util.stream.AbstractPipeline.evaluate(AbstractPipeline.java:234)
	at java.base/java.util.stream.ReferencePipeline.forEach(ReferencePipeline.java:497)
	at springfox.javadoc.doclet.SwaggerPropertiesDoclet.lambda$storeClassMethodAsProperties$5(SwaggerPropertiesDoclet.java:171)
	at java.base/java.util.Optional.ifPresent(Optional.java:183)
	at springfox.javadoc.doclet.SwaggerPropertiesDoclet.storeClassMethodAsProperties(SwaggerPropertiesDoclet.java:168)
	at springfox.javadoc.doclet.SwaggerPropertiesDoclet.processClass(SwaggerPropertiesDoclet.java:143)
	at java.base/java.util.stream.ForEachOps$ForEachOp$OfRef.accept(ForEachOps.java:183)
	at java.base/java.util.stream.ReferencePipeline$3$1.accept(ReferencePipeline.java:195)
	at java.base/java.util.stream.ReferencePipeline$2$1.accept(ReferencePipeline.java:177)
	at java.base/java.util.Iterator.forEachRemaining(Iterator.java:133)
	at java.base/java.util.Spliterators$IteratorSpliterator.forEachRemaining(Spliterators.java:1801)
	at java.base/java.util.stream.AbstractPipeline.copyInto(AbstractPipeline.java:484)
	at java.base/java.util.stream.AbstractPipeline.wrapAndCopyInto(AbstractPipeline.java:474)
	at java.base/java.util.stream.ForEachOps$ForEachOp.evaluateSequential(ForEachOps.java:150)
	at java.base/java.util.stream.ForEachOps$ForEachOp$OfRef.evaluateSequential(ForEachOps.java:173)
	at java.base/java.util.stream.AbstractPipeline.evaluate(AbstractPipeline.java:234)
	at java.base/java.util.stream.ReferencePipeline.forEach(ReferencePipeline.java:497)
	at springfox.javadoc.doclet.SwaggerPropertiesDoclet.run(SwaggerPropertiesDoclet.java:111)
	at jdk.javadoc/jdk.javadoc.internal.tool.Start.parseAndExecute(Start.java:582)
	at jdk.javadoc/jdk.javadoc.internal.tool.Start.begin(Start.java:431)
	at jdk.javadoc/jdk.javadoc.internal.tool.Start.begin(Start.java:344)
	at jdk.javadoc/jdk.javadoc.internal.tool.Main.execute(Main.java:63)
	at jdk.javadoc/jdk.javadoc.internal.tool.Main.main(Main.java:52)

[ghilainm]

@soberich Can you debug it? Or share the piece of javadoc which generate the issue?

[soberich]

@ghilainm it is not that simple as this is an actual commercial project. Can't share. Do you have any ideas what could be the reason. NPE is quite severe
the set up is

    springfoxDoclet("com.github.ghilainm.springfox-javadoc:springfox-javadoc-root:b2a7344")
    springfoxDoclet("com.github.ghilainm.springfox-javadoc:springfox-javadoc:b2a7344")
    compile("com.github.ghilainm.springfox-javadoc:springfox-javadoc-root:b2a7344")
    compile("com.github.ghilainm.springfox-javadoc:springfox-javadoc:b2a7344")

task

task generateSwaggerApiDocs(type: Javadoc) {
    manifest {
        attributes(
            "Automatic-Module-Name":  project.group,
            "Implementation-Version": project.version
        )
    }
    source = sourceSets.main.allJava
    destinationDir = reporting.file("rest-api-docs")
    options.doclet = "springfox.javadoc.doclet.SwaggerPropertiesDoclet"
    options.docletpath = configurations.springfoxDoclet.files.asType(List)
    options.classpath = configurations.runtimeClasspath.files.asType(List)
    verbose = true
}

rest setup

➜  ~ java -version
openjdk version "11.0.4" 2019-07-16
OpenJDK Runtime Environment AdoptOpenJDK (build 11.0.4+11)
OpenJDK 64-Bit Server VM AdoptOpenJDK (build 11.0.4+11, mixed mode)
➜  ~ sysctl -n machdep.cpu.brand_string
Intel(R) Core(TM) i9-8950HK CPU @ 2.90GHz
➜  ~ sw_vers 
ProductName:	Mac OS X
ProductVersion:	10.14.5
BuildVersion:	18F203

[soberich]

@ghilainm BTW, javadoc task runs fine.

[soberich]

@ghilainm
Also, if I do not ecexute `generateSwaggerApiDocsz but leave it on classpath like

springfoxDoclet("com.github.ghilainm.springfox-javadoc:springfox-javadoc-root:b2a7344")
    springfoxDoclet("com.github.ghilainm.springfox-javadoc:springfox-javadoc:b2a7344")
    compile("com.github.ghilainm.springfox-javadoc:springfox-javadoc-root:b2a7344")
    compile("com.github.ghilainm.springfox-javadoc:springfox-javadoc:b2a7344")

I got Spring-boot starts up, but with warnings like this for each model

2019-07-26 18:16:29.415  WARN 35566 --- [           main] s.d.s.p.CachingModelPropertiesProvider   : Exception calculating properties for model(com.example.domain.Device) -> ModelContext{groupName=default, type=com.example.domain.Device, isReturnType=trueview=Optional.empty}. null

and exception at the end

2019-07-26 18:16:30.077 ERROR 35566 --- [           main] d.s.w.p.DocumentationPluginsBootstrapper : Unable to scan documentation context default

java.lang.IllegalStateException: Ambiguous models equality when conditions is empty.
	at springfox.documentation.spring.web.scanners.ApiModelReader.checkCondition(ApiModelReader.java:655)
	at springfox.documentation.spring.web.scanners.ApiModelReader.mergeConditions(ApiModelReader.java:537)
	at springfox.documentation.spring.web.scanners.ApiModelReader.mergeModelBranch(ApiModelReader.java:236)
	at springfox.documentation.spring.web.scanners.ApiModelReader.read(ApiModelReader.java:149)
	at springfox.documentation.spring.web.scanners.ApiListingScanner.scan(ApiListingScanner.java:144)
	at springfox.documentation.spring.web.scanners.ApiDocumentationScanner.scan(ApiDocumentationScanner.java:69)
	at springfox.documentation.spring.web.plugins.AbstractDocumentationPluginsBootstrapper.scanDocumentation(AbstractDocumentationPluginsBootstrapper.java:97)
	at springfox.documentation.spring.web.plugins.AbstractDocumentationPluginsBootstrapper.bootstrapDocumentationPlugins(AbstractDocumentationPluginsBootstrapper.java:83)
	at springfox.documentation.spring.web.plugins.DocumentationPluginsBootstrapper.start(DocumentationPluginsBootstrapper.java:94)
	at org.springframework.context.support.DefaultLifecycleProcessor.doStart(DefaultLifecycleProcessor.java:182)
	at org.springframework.context.support.DefaultLifecycleProcessor.access$200(DefaultLifecycleProcessor.java:53)
	at org.springframework.context.support.DefaultLifecycleProcessor$LifecycleGroup.start(DefaultLifecycleProcessor.java:360)
	at org.springframework.context.support.DefaultLifecycleProcessor.startBeans(DefaultLifecycleProcessor.java:158)
	at org.springframework.context.support.DefaultLifecycleProcessor.onRefresh(DefaultLifecycleProcessor.java:122)
	at org.springframework.context.support.AbstractApplicationContext.finishRefresh(AbstractApplicationContext.java:893)
	at org.springframework.boot.web.servlet.context.ServletWebServerApplicationContext.finishRefresh(ServletWebServerApplicationContext.java:161)
	at org.springframework.context.support.AbstractApplicationContext.refresh(AbstractApplicationContext.java:552)
	at org.springframework.boot.web.servlet.context.ServletWebServerApplicationContext.refresh(ServletWebServerApplicationContext.java:140)
	at org.springframework.boot.SpringApplication.refresh(SpringApplication.java:748)
	at org.springframework.boot.SpringApplication.refreshContext(SpringApplication.java:395)
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:314)
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:1227)
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:1216)
	at com.example.Application.main(Application.java:64)

[soberich]

@ghilainm maybe as an idea for far going future in implementing such a support for SpringFox/Swagger as *Doc to OpenApi conversion it would worth to use Dokka https://github.com/Kotlin/dokka
Right now Javadoc support would limit implementation language of users to only Java. Dokka understands both Kotlin and Java and supports all types of conversions HTML <-> Kdoc <-> Javadoc.
BTW if you have an idea about how to use springfox/springfox-javadoc but not your fork with Gradle 5+. to maybe try if it'll work and if the problem is really in you fork's code, please let me know. Cheers.