[BUG][okhttp-gson] can not generate javadoc

[jmini]

Description

Introduced with issue #2994 / PR #2995 the generated javadoc now contains @http.response.details. Example from our the samples:

openapi-generator/samples/client/petstore/java/okhttp-gson/src/main/java/org/openapitools/client/api/StoreApi.java

Lines 63 to 68 in 51e7005

	* @http.response.details
	<table summary="Response Details" border="1">
	<tr><td> Status Code </td><td> Description </td><td> Response Headers </td></tr>
	<tr><td> 400 </td><td> Invalid ID supplied </td><td> - </td></tr>
	<tr><td> 404 </td><td> Order not found </td><td> - </td></tr>
	</table>

When trying to generate the javadoc artifact for the project, you get tons of errors:

cd samples/client/petstore/java/okhttp-gson
mvn javadoc:javadoc

INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  4.419 s
[INFO] Finished at: 2019-07-08T10:44:48+02:00
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-javadoc-plugin:2.10.4:javadoc (default-cli) on project petstore-okhttp-gson: An error has occurred in JavaDocs report generation: 
[ERROR] Exit code: 1 - /____/openapi-generator/samples/client/petstore/java/okhttp-gson/src/main/java/org/openapitools/client/api/AnotherFakeApi.java:63: error: unknown tag: http.response.details
[ERROR]      * @http.response.details
[ERROR]        ^
[ERROR] /____/openapi-generator/samples/client/petstore/java/okhttp-gson/src/main/java/org/openapitools/client/api/AnotherFakeApi.java:117: error: unknown tag: http.response.details
[ERROR]      * @http.response.details
[ERROR]        ^
[ERROR] /____/openapi-generator/samples/client/petstore/java/okhttp-gson/src/main/java/org/openapitools/client/api/AnotherFakeApi.java:134: error: unknown tag: http.response.details
[ERROR]      * @http.response.details
[ERROR]        ^

openapi-generator version

4.0.2

Suggest a fix

We can keep the table, but remove the @http.response.details and just put "Response details:"

@saigiridhar21, @wing328 what do you think?

[wing328]

Yes please go ahead with the fix.

[jmini]

I would put the html table before the parameters section.

    /**
     * Send-Message
     * <p>Http response details:</p>
     <table summary="Response Details" border="1">
        <tr><td> Status Code </td><td> Description </td><td> Response Headers </td></tr>
        <tr><td> 200 </td><td>  </td><td>  -  </td></tr>
     </table>
     * @param sendMessageRequestBody  (required)
     * @throws ApiException If fail to call the API, e.g. server error or cannot deserialize the response body
     */
    public void sendMessage(SendMessageRequestBody sendMessageRequestBody) throws ApiException

IMO it looks better (preview of the javadoc in Eclipse IDE):

[jmini]

Wait, never-mind the issue is how the maven build is configured.

When the configuration bloc is correctly defined, you get decent result:

[saigiridhar21]

@jmini Do you mean that the configuration block is incorrectly configured in pom.xml?

[jmini]

Thank you for the quick feedback. I have proposed a fix in #3302. Feel free to review.