How to use/run it exactly? #9

dagnelies · 2018-07-17T14:41:20Z

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?

The text was updated successfully, but these errors were encountered:

dilipkrish · 2018-07-19T00:57:29Z

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?

dagnelies · 2018-07-20T09:22:56Z

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.

dagnelies · 2018-07-20T11:00:01Z

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.

dilipkrish · 2018-07-24T11:28:26Z

@dagnelies once you have the property file in the class path, its just a matter of declaring it as a property source.

dagnelies · 2018-07-24T12:23:06Z

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

dilipkrish · 2018-07-24T12:48:37Z

@dagnelies it shouldnt be, Ill take a look at it... re-opening, this ticket /c @neumaennl

neumaennl · 2018-07-29T13:20:11Z

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?

dilipkrish · 2018-08-04T00:58:02Z

It is possible. I can take a look

vanduc1102 · 2018-08-10T02:05:47Z

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:

dilipkrish · 2018-08-12T15:48:54Z

@vanduc1102 seems like you're not able to resolve the artifact. Perhaps your plugin repositories doesnt include maven central

vladoltean · 2018-09-27T12:55:04Z

@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

vladoltean · 2018-10-01T09:56:00Z

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?

dilipkrish · 2018-11-09T12:01:01Z

@vladoltean try using 2.9.2. I believe 2.9.0 had trouble syncing with maven central

cbornet · 2018-12-20T17:24:46Z

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

cbornet · 2018-12-26T13:29:16Z

Actually the current master depends on springfox-swagger2 2.9.2. So could a new release be published?

dktsni · 2019-04-02T23:46:32Z

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 ?

eranation · 2019-04-17T00:12:37Z

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)?

Sam-Kruglov · 2019-06-22T07:44:02Z

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

Sam-Kruglov · 2019-06-22T07:50:47Z

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

Flying--Dutchman · 2020-07-18T21:30:38Z

Any update on this?

How can one set this up with SpringFox 3?

dilipkrish · 2020-07-18T22:19:51Z

Haven't had time to revisit this. Would love to get this up to speed. Any takers?

dilipkrish added the question Further information is requested label Jul 19, 2018

dagnelies closed this as completed Jul 24, 2018

dilipkrish reopened this Jul 24, 2018

dilipkrish added the bug Something isn't working label Aug 4, 2018

dktsni mentioned this issue May 6, 2019

Cleanup javadoc on the server side Decathlon/ara#99

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

How to use/run it exactly? #9

How to use/run it exactly? #9

dagnelies commented Jul 17, 2018

dilipkrish commented Jul 19, 2018

dagnelies commented Jul 20, 2018 •

edited

dagnelies commented Jul 20, 2018

dilipkrish commented Jul 24, 2018

dagnelies commented Jul 24, 2018

dilipkrish commented Jul 24, 2018

neumaennl commented Jul 29, 2018

dilipkrish commented Aug 4, 2018

vanduc1102 commented Aug 10, 2018

dilipkrish commented Aug 12, 2018

vladoltean commented Sep 27, 2018 •

edited

vladoltean commented Oct 1, 2018 •

edited

dilipkrish commented Nov 9, 2018

cbornet commented Dec 20, 2018 •

edited

cbornet commented Dec 26, 2018

dktsni commented Apr 2, 2019

eranation commented Apr 17, 2019

Sam-Kruglov commented Jun 22, 2019

Sam-Kruglov commented Jun 22, 2019

Flying--Dutchman commented Jul 18, 2020

dilipkrish commented Jul 18, 2020

How to use/run it exactly? #9

How to use/run it exactly? #9

Comments

dagnelies commented Jul 17, 2018

dilipkrish commented Jul 19, 2018

dagnelies commented Jul 20, 2018 • edited

dagnelies commented Jul 20, 2018

dilipkrish commented Jul 24, 2018

dagnelies commented Jul 24, 2018

dilipkrish commented Jul 24, 2018

neumaennl commented Jul 29, 2018

dilipkrish commented Aug 4, 2018

vanduc1102 commented Aug 10, 2018

dilipkrish commented Aug 12, 2018

vladoltean commented Sep 27, 2018 • edited

vladoltean commented Oct 1, 2018 • edited

dilipkrish commented Nov 9, 2018

cbornet commented Dec 20, 2018 • edited

cbornet commented Dec 26, 2018

dktsni commented Apr 2, 2019

eranation commented Apr 17, 2019

Sam-Kruglov commented Jun 22, 2019

Sam-Kruglov commented Jun 22, 2019

Flying--Dutchman commented Jul 18, 2020

dilipkrish commented Jul 18, 2020

dagnelies commented Jul 20, 2018 •

edited

vladoltean commented Sep 27, 2018 •

edited

vladoltean commented Oct 1, 2018 •

edited

cbornet commented Dec 20, 2018 •

edited