search

springfox / springfox-javadoc

Ability to use Javadoc for documentation for generating OpenAPI specifications
Apache License 2.0
17 stars 15 forks source link

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

Open ghilainm opened 5 years ago

ghilainm commented 5 years ago

The following changes have been performed:

ghilainm commented 5 years ago

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

ghilainm commented 5 years ago

@dilipkrish any news?

soberich commented 5 years ago

@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 commented 5 years ago

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

soberich commented 5 years ago

@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 commented 5 years ago

@ghilainm BTW, javadoc task runs fine.

soberich commented 5 years ago

@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 commented 5 years ago

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