[JAVA] Generated API client contains invalid JavaDoc

[michael-simons]

Description

I'm using swagger-codegen to generate a client (SDK) for https://api.aixigo.com/apidocs/apidocs/swagger.json (current snapshot attached for reference).

The source code can be compiled and tested via standard Maven package command, but during the attach JavaDoc phase the JavaDoc compiler fails with several wrong, generated comments, i.e.

This one fails because the reference to PmsMeasure must be fully qualified or imported:

[ERROR] /Users/msimons/tmp/generatedcodde/tmp/src/main/java/io/swagger/client/api/ProcessAutomationApi.java:3683: error: reference not found
[ERROR]      * This resource consumes {@link PmsTask} and maps them to {@link PmsMeasure} containing the target allocation for the respective contract.
[ERROR] 

This one I cannot explain:

[ERROR] /Users/msimons/tmp/generatedcodde/tmp/src/main/java/io/swagger/client/api/RebalancingApi.java:1176: error: unexpected text
[ERROR]      * This resource consumes a {@link List< String >} contractIds and maps them to {@link ContractTargetAssetAllocations} containing the target allocations for the respective contract.

This one are invalid entities:

/Users/msimons/tmp/generatedcodde/tmp/src/main/java/io/swagger/client/api/RebalancingApi.java:1181: warning - Tag @link:illegal character: "38" in "List< String >"

Swagger-codegen version

2.3.1, installed via Homebrew
Here are Maven and Java Versions:

mvn --version
Apache Maven 3.5.0 (ff8f5e7444045639af65f6095c62210b5713f426; 2017-04-03T21:39:06+02:00)
Maven home: /usr/local/Cellar/maven/3.5.0/libexec
Java version: 1.8.0_152, vendor: Oracle Corporation
Java home: /Library/Java/JavaVirtualMachines/jdk1.8.0_152.jdk/Contents/Home/jre
Default locale: de_DE, platform encoding: UTF-8
OS name: "mac os x", version: "10.13.2", arch: "x86_64", family: "mac"

Swagger declaration file content or url

https://api.aixigo.com/apidocs/apidocs/swagger.json
swagger.json.zip

Command line used for generation

swagger-codegen generate -i  https://api.aixigo.com/apidocs/apidocs/swagger.json -l java -o tmp

Steps to reproduce

swagger-codegen generate -i  https://api.aixigo.com/apidocs/apidocs/swagger.json -l java -o tmp
cd tmp
mvn clean package

There are several options to fix this. On is specifying <failOnError>false</failOnError> in the generated pom, the other ones are generating correct JavaDoc.

[eivinhb]

As I see it, this is not a bug in the swagger codegen for java.

I the swagger.json attached to this issue this line appairs:

"description": "This resource consumes a {@link List< String >} contractIds and maps them to {@link ContractTargetAssetAllocations} containing the target allocations for the respective contract.",

And it is the < which are generated into {@link List< String >} that is causing the build error. In addition the class ContractTargetAssetAllocations referenced in the description is non existent in swagger.json.

Either:

1. The code that is generating the swagger.json-file is making this description out of a type signature
2. There is an error in a java-doc from the API that the swagger.json is generated from.

I am guessing the latter is true since the description contains classes not referenced in the swagger.json.

If you change the faulty part into {@link List}<{@link String}>, will it then compile correctly? Either way, I think that is a better link to a List with generics is to link to both of the types. Also make shure that the type ContractTargetAssetAllocations is indeed in the api if the doc is suppose to be able to link to it.