search

OpenAPITools / openapi-generator

OpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and configuration automatically given an OpenAPI Spec (v2, v3)
https://openapi-generator.tech
Apache License 2.0
21.85k stars 6.59k forks source link

[BUG][Java][client] `mvn package` fails on Javadoc error #3272

Open bkabrda opened 5 years ago

bkabrda commented 5 years ago

Bug Report Checklist

Description

Generated Java client (okhttp-gson) fails to build, erroring out on javadoc issues. This is reproducible even on samples/client/petstore/java/okhttp-gson for me. The output of mvn package is as follows:

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-javadoc-plugin:2.10.4:jar (attach-javadocs) on project petstore-okhttp-gson: MavenReportException: Error while generating Javadoc:
[ERROR] Exit code: 1 - javadoc: error - The code being documented uses modules but the packages defined in http://docs.oracle.com/javase/8/docs/api/ are in the unnamed module.
[ERROR] /Users/slavek.kabrda/programming/openapi-generator/samples/client/petstore/java/okhttp-gson/src/main/java/org/openapitools/client/api/AnotherFakeApi.java:64: error: attribute not supported in HTML5: summary
[ERROR]      <table summary="Response Details" border="1">
[ERROR]             ^
# and many more error lines repeating the "table summary" error

It seems that there are 2 separate issues - the "table summary" being incorrect for HTML 5 and the other: "The code being documented uses modules but the packages defined in http://docs.oracle.com/javase/8/docs/api/ are in the unnamed module."

openapi-generator version

Seems to be both in 4.0.2 and current master.

OpenAPI declaration file content or url

Use the one included in samples.

Command line used for generation

None, just trying to build samples/client/petstore/java/okhttp-gson after cloning the repo.

Steps to reproduce
$ cd samples/client/petstore/java/okhttp-gson
$ mvn package
Related issues/PRs

None AFAICS.

Suggest a fix

For the first problem ("table summary"), we could probably easily fix the HTML to produce something that is compatible with HTML 5.

For the other issue, I guess the problem is a version combination of my JDK/maven, but I'm not a Java expert, so I don't know. Quick googling around didn't really help. My environment:

$ mvn -v
Apache Maven 3.6.1 (d66c9c0b3152b2e69ee9bac180bb8fcc8e6af555; 2019-04-04T21:00:29+02:00)
Maven home: /usr/local/Cellar/maven/3.6.1/libexec
Java version: 12.0.1, vendor: AdoptOpenJDK, runtime: /Library/Java/JavaVirtualMachines/adoptopenjdk-12.0.1.jdk/Contents/Home
Default locale: en_CZ, platform encoding: UTF-8
OS name: "mac os x", version: "10.14.5", arch: "x86_64", family: "mac"
wing328 commented 5 years ago

I couldn't repeat the issue locally (as I'm using Java 8). I'll leverage the CI to test different versions of JVM later to see if the issue occurs for a specified JVM version.

For the time being, please use -Dmaven.javadoc.skip=true as a workaround

bkabrda commented 5 years ago

FTR, I could only reproduce the issue using OpenJDK 11 and 12 from adoptopenjdk [1]. With their OpenJDK 8, this works fine for me too.

[1] https://github.com/AdoptOpenJDK/homebrew-openjdk

jmini commented 5 years ago

~Possible duplicate issue: #3299.~ ~I think I have fixed it with https://github.com/OpenAPITools/openapi-generator/pull/3302~

~Can you give 4.0.3 a try?~

Can you provide what the correct HTML should be? It is easy to change.

In #3302 I have activated verification of Javadoc task in our CI, but I guess we are only testing with Java 8. I need to check with @wing328 how we can run mvn --quiet javadoc:javadoc -Psamples.circleci on Java 11.

softdays commented 4 years ago

The configuration below of the javadoc plugin works for me with AdoptOpenJDK 11.0.6:

      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>3.1.1</version>
        <executions>
          <execution>
            <id>attach-javadocs</id>
            <goals>
              <goal>jar</goal>
            </goals>
          </execution>
        </executions>
        <configuration>
          <source>8</source>
          <doclint>none</doclint>
          <tags>
            <tag>
              <name>http.response.details</name>
              <placement>a</placement>
              <head>Http Response Details:</head>
            </tag>
          </tags>
        </configuration>
      </plugin>
miguelcss commented 2 years ago

Hello I'm facing similar issue with comand line openapi-generator generate

What would be the workaround for command line ? Could not find javadoc option here: https://github.com/OpenAPITools/openapi-generator/blob/master/docs/generators/java.md

My env:

openapi-generator-cli 5.3.0
openjdk 11.0.12 2021-07-20

Thank you for info

wing328 commented 2 years ago

can you please try with the latest stable version v5.4.0?

an alternative is to use the docker images: https://hub.docker.com/r/openapitools/openapi-generator-cli

miguelcss commented 2 years ago

@wing328 thank you for reply, I tried it and still same issue (5.4.0 and openjdk 17).

For anyone facing similar issue, not ideal but I've disabled doclint in build.gradle like so:


javadoc {
    if(JavaVersion.current().isJava8Compatible()) {
        options.addStringOption('Xdoclint:none', '-quiet')
    }
}
nfalco79 commented 1 year ago

We have the same issue using library=jersey2, generatorName= java, JVM graalVM mandrel 22.3 Issue:

[ERROR] target\generated-sources\openapi\src\main\java\it\acme\client\stream\it\acme\pnd\stream\api\NotificationPriceApi.java:58: error: attribute not supported in HTML5: summary
[ERROR]     <table summary="Response Details" border="1">

Generated code:

  /**
   * Retrieve notification price and effective date
   * Usata dalla PA per recuperare il costo di notificazione tramite  l&#39;identificativo della posizione debitoria paTaxId e noticeCode.
   * @param paTaxId Payment PA fiscal code (required)
   * @param noticeCode Payment notice number  numero avviso (required)
   * @return NotificationPriceResponse
   * @throws ApiException if fails to make API call
   * @http.response.details
     <table summary="Response Details" border="1">
       <tr><td> Status Code </td><td> Description </td><td> Response Headers </td></tr>
       <tr><td> 200 </td><td> OK </td><td>  -  </td></tr>
       <tr><td> 400 </td><td> Invalid input </td><td>  -  </td></tr>
       <tr><td> 404 </td><td> Not Found </td><td>  -  </td></tr>
       <tr><td> 500 </td><td> Internal Server Error </td><td>  -  </td></tr>
     </table>
   */
  public NotificationPriceResponse retrieveNotificationPrice(String paTaxId, String noticeCode) throws ApiException {

YAML: openapi.txt

gbrinkmann commented 1 year ago

I couldn't repeat the issue locally (as I'm using Java 8). I'll leverage the CI to test different versions of JVM later to see if the issue occurs for a specified JVM version.

For the time being, please use -Dmaven.javadoc.skip=true as a workaround

Just a quick additional note: I'm on openapi-generator-maven-plugin 7.0.1 and regarding this bug I prefer https://maven.apache.org/plugins/maven-javadoc-plugin/examples/exclude-package-names.html (when the generated client is just part of a bigger project).