springfox-javadoc
springfox-javadoc copied to clipboard
springfox
How to use/run it exactly?
So... like the README said, I added the plugin snippet to the pom.xml.
I added it in
<project
...
<build>
<plugins>
>>> HERE <<<
Is that right?
I also got the following warning:
Plugin execution not covered by lifecycle configuration: org.apache.maven.plugins:maven-javadoc-plugin:2.10.4:javadoc
(execution: default, phase: process-classes)
By simply running the project (using spring boot), I still see no javadoc being used in swagger descriptions. I guess I'm missing a step but I'm a bit in the dark here. Could anyone please point me in the right direction?
It should produce a property file in your resources/classpath and you need to include the property file as a PropertySource. This can be resolved using property resolution. Correct @neumaennl?
Well ...I don't see any properties file produced anywhere ...so I guess I'm missing something basic.
IMHO this plugin would be fantastic ...it's kind of a pity that its usage is left in the dark.
Ok, I'm one step further. I thought you have to either "run" the project normally, or to generate the javadoc to produce that file.
It turns out you have to package it using mvn package first.
I also had an empty ${project.build.outputDirectory}/META-INF/springfox.javadoc.properties for a while because I forgot to edit the <subpackages>...</subpackages> value.
Now I have the filled properties file ...but it is not yet used by swagger. That's probably the last step to find out.
@dagnelies once you have the property file in the class path, its just a matter of declaring it as a property source.
...Ok, I lastly got it to work. Following annotations must be added in the spring boot application:
@Import(springfox.javadoc.configuration.JavadocPluginConfiguration.class)
@PropertySource("springfox.javadoc.properties")
And on the way to there, I had to first use mvn package, then copy the ${project.build.outputDirectory}/META-INF/springfox.javadoc.properties to src/main/resources to use it.
Somehow, the whole process is fairly contrived at the moment.
@dagnelies it shouldnt be, Ill take a look at it... re-opening, this ticket /c @neumaennl
Hi,
@dagnelies adding the doclet in the correct place in the maven pom (like you did) and then using @Import(springfox.javadoc.configuration.JavadocPluginConfiguration.class) should have been enough. You shouldn't have to use @PropertySource("springfox.javadoc.properties"), since this is already in the JavadocPluginConfiguration. The additional mvn package to copy the properties file should also not be necessary.
@dilipkrish I remember you changed some stuff to facilitate building with gradle, but you didn't upgrade the pom.xml accordingly. Could it be that there are some unwanted side effects because of this?
I cant make it works here is my pom
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.mycompany</groupId>
<artifactId>project-code-pay</artifactId>
<version>1.0.0-SNAPSHOT</version>
<properties>
<java.version>1.8</java.version>
</properties>
<dependencies>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-javadoc</artifactId>
<version>0.9.4</version>
</dependency>
</dependencies>
<build>
<plugins>
<!-- swagger java doc -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.10.4</version>
<executions>
<execution>
<goals>
<goal>javadoc</goal>
</goals>
<phase>process-classes</phase>
<configuration>
<doclet>springfox.javadoc.doclet.SwaggerPropertiesDoclet</doclet>
<docletArtifact>
<groupId>io.springfox</groupId>
<artifactId>springfox-javadoc</artifactId>
<version>0.9.4</version>
</docletArtifact>
<additionalparam>
-classdir ${project.build.outputDirectory}
</additionalparam>
<sourcepath>${project.build.sourceDirectory}</sourcepath>
<subpackages>com.mycompany.project_code.controller.api</subpackages>
<useStandardDocletOptions>false</useStandardDocletOptions>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>
error:
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 3.944 s
[INFO] Finished at: 2018-08-10T09:02:54+07:00
[INFO] Final Memory: 46M/407M
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-javadoc-plugin:2.10.4:javadoc (default) on project project-code: An error has occurred in JavaDocs report generation: Unable to resolve artifact:groupId = 'io.springfox'
[ERROR] artifactId = 'springfox-javadoc'
[ERROR] version = '0.9.4': Missing:
@vanduc1102 seems like you're not able to resolve the artifact. Perhaps your plugin repositories doesnt include maven central
@dilipkrish I have a similar issue as @vanduc1102.
...
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
...
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.10.4</version>
<executions>
<execution>
<goals>
<goal>javadoc</goal>
</goals>
<phase>process-classes</phase>
<configuration>
<doclet>springfox.javadoc.doclet.SwaggerPropertiesDoclet</doclet>
<docletArtifact>
<groupId>io.springfox</groupId>
<artifactId>springfox-javadoc</artifactId>
<version>0.9.4</version>
</docletArtifact>
<additionalparam>
-classdir ${project.build.outputDirectory}
</additionalparam>
<sourcepath>${project.build.sourceDirectory}</sourcepath>
<subpackages>com.my.controller.vlad</subpackages>
<useStandardDocletOptions>false</useStandardDocletOptions>
</configuration>
</execution>
</executions>
</plugin>
...
Error when running mvn package states:
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-javadoc-plugin:2.10.4:javadoc (default) on project vlad: An error has occurred in JavaDocs report generation: Unable to resolve artifact:groupId = 'io.springfox'
[ERROR] artifactId = 'springfox-javadoc'
[ERROR] version = '0.9.4': Missing:
[ERROR] ----------
[ERROR] 1) io.springfox:springfox-swagger2:jar:2.9.0
[ERROR]
[ERROR] Try downloading the file manually from the project website.
[ERROR]
[ERROR] Then, install it using the command:
[ERROR] mvn install:install-file -DgroupId=io.springfox -DartifactId=springfox-swagger2 -Dversion=2.9.0 -Dpackaging=jar -Dfile=/path/to/file
[ERROR]
[ERROR] Alternatively, if you host your own repository you can deploy the file there:
[ERROR] mvn deploy:deploy-file -DgroupId=io.springfox -DartifactId=springfox-swagger2 -Dversion=2.9.0 -Dpackaging=jar -Dfile=/path/to/file -Durl=[url] -DrepositoryId=[id]
But I don't want to manually install it, if that is an option
So, I have solved the problem. I had to import from http://repo.spring.io/plugins-release:
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.0</version>
</dependency>
since springfox-javadoc version 0.9.4 depends on it.
Question: Should javadoc used on models be reflected in the api documentation by this plugin?
@vladoltean try using 2.9.2. I believe 2.9.0 had trouble syncing with maven central
@dilipkrish the problem is that maven-javadoc-plugin downloads the 2.9.0 version whatever your own dependencies are. Could a 0.9.5 be released that depends on springfox-swagger2:2.9.2 ? I can do the PR if needed.
Also I think it's better to generate the file in generate-sources phase so you don't have to completely package the jar (and pass the tests, etc...).
Actually the current master depends on springfox-swagger2 2.9.2. So could a new release be published?
Hi @dilipkrish,
First, thanks for your work on SpringFox Javadoc :)
I must say that I got the same problem than the others above with the dependency resolution of springfox-swagger2.
Here is what I tried :
- Add a dependency to springfox-swagger2 at version 2.9.2
- Add an exclusion of springfox-swagger2 in the springfox-javadoc dependency
- Add the spring repository as a remote repository in my pom.xml
None of this works. What seems strange, is that with the 2 first cases, Maven won't be able to download springfox-swagger2:2.9.0, and in the third case, it downloads it, but springfox-javadoc still try to download springfox-swagger2:2.9.0 from the maven central, which fails, and breaks my build.
Have you some news about this issue ?
Same issue here, doesn't work with io.springfox:springfox-swagger2::2.9.2 (latest) @dilipkrish any chance you can push a version bump (or mark that dependency as optional / provided)?
It builds if you add this repository
<repositories>
<repository>
<id>spring.releases</id>
<url>https://repo.spring.io/plugins-release/</url>
<snapshots><enabled>false</enabled></snapshots>
</repository>
</repositories>
But when you open swagger UI, then nothing has changed
Maybe you can just reuse this project? @dilipkrish So, you add this doclet instead
<plugin>
<artifactId>maven-javadoc-plugin</artifactId>
<extensions>true</extensions>
<executions>
<execution>
<id>generate-javadoc-json</id>
<phase>compile</phase>
<goals>
<goal>javadoc-no-fork</goal>
</goals>
<configuration>
<doclet>capital.scalable.restdocs.jsondoclet.ExtractDocumentationAsJsonDoclet</doclet>
<docletArtifact>
<groupId>capital.scalable</groupId>
<artifactId>spring-auto-restdocs-json-doclet</artifactId>
<version>2.0.5</version>
</docletArtifact>
<destDir>generated-javadoc-json</destDir>
<reportOutputDirectory>${project.build.directory}</reportOutputDirectory>
<useStandardDocletOptions>false</useStandardDocletOptions>
<show>package</show>
</configuration>
</execution>
</executions>
</plugin>
Then it creates a folder with all the javadocs in JSON format, e.g.:
{
"comment": "",
"fields": {
"service": {
"comment": "",
"tags": {}
}
},
"methods": {
"get": {
"comment": "JavaDoc on method",
"parameters": {
"id": "javadoc on param"
},
"tags": {}
}
}
}
This is used by Auto REST Docs https://github.com/ScaCap/spring-auto-restdocs
Haven't had time to revisit this. Would love to get this up to speed. Any takers?