swagger-api/swagger-codegen

[JAVA] Generated API client contains invalid JavaDoc

Open

#7548 opened on Feb 1, 2018

View on GitHub
 (1 comment) (0 reactions) (0 assignees)HTML (12,701 stars) (5,474 forks)batch import
Client: JavaFeature: DocumentationIssue: Non-operationalhelp wanted

Description

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.

Contributor guide

Tech stack
java
Domain
backendapi
Issue type
bug
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
stale
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
JavaMavenMustache templates
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
40
Research direction
The issue is that generated JavaDoc contains invalid @link references, some missing imports and illegal characters. To fix, examine the mustache templates in modules/swagger codegen/src/main/resources/Java/libraries/okhttp gson/ (or relevant library) that generate the JavaDoc comments for API methods. Ensure that @link references use fully qualified class names or are imported correctly. Also check for improper escaping of HTML entities like &lt; and &gt;. Consider adding a test case reproducing the issue with the provided swagger.json to verify the fix.