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

ghilainm · 2019-04-26T08:19:05Z

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

… and make it compatible with Gradle build

…d added Gradle example

…working

ghilainm · 2019-05-28T05:25:52Z

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

ghilainm · 2019-06-28T15:44:26Z

@dilipkrish any news?

soberich · 2019-07-26T15:34:14Z

@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 · 2019-07-26T15:38:34Z

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

soberich · 2019-07-26T15:48:52Z

@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 · 2019-07-26T16:07:30Z

@ghilainm BTW, javadoc task runs fine.

soberich · 2019-07-26T16:20:40Z

@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 · 2019-07-27T19:43:11Z

@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.

ghilaima added 2 commits April 25, 2019 18:47

springfox#13: Update Doclet in order to make it compatible with Java9…

824c638

… and make it compatible with Gradle build

springfox#13: Added support for retrieving Javadoc from controller an…

85c4534

…d added Gradle example

ghilainm changed the title ~~Feature/#13 support for jdk9 controller doc gradle example + refactoring~~ Feature/#13 support for jdk9 - controller doc - gradle example - refactoring Apr 26, 2019

ghilaima added 13 commits April 26, 2019 10:27

Update circleci build image for jdk9

05cb0b8

Fixed checkstyle issues

419ed55

Fixed test on CI

a170aed

Configure correctly test report exports

afbdfe8

Removed useless stages

f047715

Fixed step name

361e7da

Added missing maven plugin

ef16346

Added descriptor for jitpack

acaf694

springfox#14: New Feature > Document model properties using javadoc

58ac347

Updated readme

3aa6f40

Fixed checkstyle errors

ccac409

Fixed checkstyle in test

f6e5ef1

Added example to showcase that model documentation for deep field is …

b2a7344

…working

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

ghilainm commented Apr 26, 2019 •

edited

Loading

ghilainm commented May 28, 2019

ghilainm commented Jun 28, 2019

soberich commented Jul 26, 2019

ghilainm commented Jul 26, 2019

soberich commented Jul 26, 2019

soberich commented Jul 26, 2019

soberich commented Jul 26, 2019 •

edited

Loading

soberich commented Jul 27, 2019

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

Are you sure you want to change the base?

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

Conversation

ghilainm commented Apr 26, 2019 • edited Loading

ghilainm commented May 28, 2019

ghilainm commented Jun 28, 2019

soberich commented Jul 26, 2019

ghilainm commented Jul 26, 2019

soberich commented Jul 26, 2019

soberich commented Jul 26, 2019

soberich commented Jul 26, 2019 • edited Loading

soberich commented Jul 27, 2019

ghilainm commented Apr 26, 2019 •

edited

Loading

soberich commented Jul 26, 2019 •

edited

Loading