search

springfox / springfox-javadoc

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

How to use/run it exactly? #9

Open dagnelies opened 6 years ago

dagnelies commented 6 years ago

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?

dilipkrish commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

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

dagnelies commented 6 years ago

...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 commented 6 years ago

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

neumaennl commented 6 years ago

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 commented 6 years ago

It is possible. I can take a look

vanduc1102 commented 6 years ago

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 commented 6 years ago

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

vladoltean commented 5 years ago

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

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

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

cbornet commented 5 years ago

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

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

dktsni commented 5 years ago

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 :

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

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

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

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 commented 4 years ago

Any update on this?

How can one set this up with SpringFox 3?

dilipkrish commented 4 years ago

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