JavaDoc fixes for Java/RESTEasy client (#151)

OpenAPITools · May 26, 2018 · 4d7ff8c · 4d7ff8c
1 parent 6f23b50
commit 4d7ff8c
Show file tree

Hide file tree

Showing 13 changed files with 117 additions and 19 deletions.
diff --git a/modules/openapi-generator/src/main/resources/Java/libraries/resteasy/ApiClient.mustache b/modules/openapi-generator/src/main/resources/Java/libraries/resteasy/ApiClient.mustache
@@ -85,6 +85,7 @@ public class ApiClient {
 
   /**
    * Gets the JSON instance to do JSON serialization and deserialization.
+   * @return the JSON utility class
    */
   public JSON getJSON() {
     return json;
@@ -110,20 +111,23 @@ public class ApiClient {
 
   /**
    * Gets the status code of the previous request
+   * @return the status code of the previous request
    */
   public int getStatusCode() {
     return statusCode;
   }
 
   /**
    * Gets the response headers of the previous request
+   * @return the response headers of the previous request
    */
   public Map<String, List<String>> getResponseHeaders() {
     return responseHeaders;
   }
 
   /**
    * Get authentications (key: authentication name, value: authentication).
+   * @return the authentications
    */
   public Map<String, Authentication> getAuthentications() {
     return authentications;
@@ -141,6 +145,7 @@ public class ApiClient {
 
   /**
    * Helper method to set username for the first HTTP basic authentication.
+   * @param username the username
    */
   public void setUsername(String username) {
     for (Authentication auth : authentications.values()) {
@@ -154,6 +159,7 @@ public class ApiClient {
 
   /**
    * Helper method to set password for the first HTTP basic authentication.
+   * @param password the password
    */
   public void setPassword(String password) {
     for (Authentication auth : authentications.values()) {
@@ -167,6 +173,7 @@ public class ApiClient {
 
   /**
    * Helper method to set API key value for the first API key authentication.
+   * @param apiKey the API key
    */
   public void setApiKey(String apiKey) {
     for (Authentication auth : authentications.values()) {
@@ -180,6 +187,7 @@ public class ApiClient {
 
   /**
    * Helper method to set API key prefix for the first API key authentication.
+   * @param apiKeyPrefix the API key prefix
    */
   public void setApiKeyPrefix(String apiKeyPrefix) {
     for (Authentication auth : authentications.values()) {
@@ -193,6 +201,7 @@ public class ApiClient {
 
   /**
    * Helper method to set access token for the first OAuth2 authentication.
+   * @param accessToken the access token
    */
   public void setAccessToken(String accessToken) {
     for (Authentication auth : authentications.values()) {
@@ -206,6 +215,8 @@ public class ApiClient {
 
   /**
    * Set the User-Agent header's value (by adding to the default header map).
+   * @param userAgent the User-Agent header value
+   * @return this {@code ApiClient}
    */
   public ApiClient setUserAgent(String userAgent) {
     addDefaultHeader("User-Agent", userAgent);
@@ -217,6 +228,7 @@ public class ApiClient {
    *
    * @param key The header's key
    * @param value The header's value
+   * @return this {@code ApiClient}
    */
   public ApiClient addDefaultHeader(String key, String value) {
     defaultHeaderMap.put(key, value);
@@ -225,6 +237,7 @@ public class ApiClient {
 
   /**
    * Check that whether debugging is enabled for this API client.
+   * @return {@code true} if debugging is enabled for this API client
    */
   public boolean isDebugging() {
     return debugging;
@@ -234,6 +247,7 @@ public class ApiClient {
    * Enable/disable debugging for this API client.
    *
    * @param debugging To enable (true) or disable (false) debugging
+   * @return this {@code ApiClient}
    */
   public ApiClient setDebugging(boolean debugging) {
     this.debugging = debugging;
@@ -247,7 +261,8 @@ public class ApiClient {
    * with file response. The default value is <code>null</code>, i.e. using
    * the system's default tempopary folder.
    *
-   * @see https://docs.oracle.com/javase/7/docs/api/java/io/File.html#createTempFile(java.lang.String,%20java.lang.String,%20java.io.File)
+   * @return the temporary folder path
+   * @see <a href="https://docs.oracle.com/javase/7/docs/api/java/io/File.html#createTempFile(java.lang.String,%20java.lang.String,%20java.io.File)"></a>
    */
   public String getTempFolderPath() {
     return tempFolderPath;
@@ -260,13 +275,16 @@ public class ApiClient {
 
   /**
    * Get the date format used to parse/format date parameters.
+   * @return the date format used to parse/format date parameters
    */
   public DateFormat getDateFormat() {
     return dateFormat;
   }
 
   /**
    * Set the date format used to parse/format date parameters.
+   * @param dateFormat a date format used to parse/format date parameters
+   * @return this {@code ApiClient}
    */
   public ApiClient setDateFormat(DateFormat dateFormat) {
     this.dateFormat = dateFormat;
@@ -277,6 +295,8 @@ public class ApiClient {
 
   /**
    * Parse the given string into Date object.
+   * @param str a string to parse
+   * @return a {@code Date} object
    */
   public Date parseDate(String str) {
     try {
@@ -288,13 +308,17 @@ public class ApiClient {
 
   /**
    * Format the given Date object into string.
+   * @param date a {@code Date} object to format
+   * @return the {@code String} version of the {@code Date} object
    */
   public String formatDate(Date date) {
     return dateFormat.format(date);
   }
 
   /**
    * Format the given parameter object into string.
+   * @param param an object to format
+   * @return the {@code String} version of the object
    */
   public String parameterToString(Object param) {
     if (param == null) {
@@ -430,6 +454,8 @@ public class ApiClient {
 
   /**
    * Escape the given string to be used as URL query value.
+   * @param str a {@code String} to escape
+   * @return the escaped version of the {@code String}
    */
   public String escapeString(String str) {
     try {
@@ -442,6 +468,11 @@ public class ApiClient {
   /**
    * Serialize the given Java object into string entity according the given
    * Content-Type (only JSON is supported for now).
+   * @param obj the object to serialize
+   * @param formParams the form parameters
+   * @param contentType the content type
+   * @return an {@code Entity}
+   * @throws ApiException on failure to serialize
    */
   public Entity<?> serialize(Object obj, Map<String, Object> formParams, String contentType) throws ApiException {
     Entity<?> entity = null;
@@ -476,6 +507,11 @@ public class ApiClient {
 
   /**
    * Deserialize response body to Java object according to the Content-Type.
+   * @param <T> a Java type parameter
+   * @param response the response body to deserialize
+   * @param returnType a Java type to deserialize into
+   * @return a deserialized Java object
+   * @throws ApiException on failure to deserialize
    */
   public <T> T deserialize(Response response, GenericType<T> returnType) throws ApiException {
     if (response == null || returnType == null) {
@@ -504,6 +540,8 @@ public class ApiClient {
 
   /**
    * Download file from the given response.
+   * @param response a response
+   * @return a file from the given response
    * @throws ApiException If fail to read file content from response and write to disk
    */
   public File downloadFileFromResponse(Response response) throws ApiException {
@@ -560,6 +598,7 @@ public class ApiClient {
   /**
    * Invoke API by sending HTTP request with the given options.
    *
+   * @param <T> a Java type parameter
    * @param path The sub-path of the HTTP URL
    * @param method The request method, one of "GET", "POST", "PUT", "HEAD" and "DELETE"
    * @param queryParams The query parameters
@@ -571,6 +610,7 @@ public class ApiClient {
    * @param authNames The authentications to apply
    * @param returnType The return type into which to deserialize the response
    * @return The response body in type of string
+   * @throws ApiException if the invocation failed
    */
   public <T> T invokeAPI(String path, String method, List<Pair> queryParams, Object body, Map<String, String> headerParams, Map<String, Object> formParams, String accept, String contentType, String[] authNames, GenericType<T> returnType) throws ApiException {
     updateParamsForAuth(authNames, queryParams, headerParams);

diff --git a/modules/openapi-generator/src/main/resources/Java/libraries/resteasy/JSON.mustache b/modules/openapi-generator/src/main/resources/Java/libraries/resteasy/JSON.mustache
@@ -36,6 +36,7 @@ public class JSON implements ContextResolver<ObjectMapper> {
 
   /**
    * Set the date format for JSON (de)serialization with Date properties.
+   * @param dateFormat the date format to set
    */
   public void setDateFormat(DateFormat dateFormat) {
     mapper.setDateFormat(dateFormat);

diff --git a/modules/openapi-generator/src/main/resources/Java/libraries/resteasy/api.mustache b/modules/openapi-generator/src/main/resources/Java/libraries/resteasy/api.mustache
@@ -43,7 +43,7 @@ public class {{classname}} {
    * {{summary}}
    * {{notes}}{{#allParams}}
    * @param {{paramName}} {{description}}{{#required}} (required){{/required}}{{^required}} (optional{{#defaultValue}}, default to {{.}}{{/defaultValue}}){{/required}}{{/allParams}}{{#returnType}}
-   * @return {{{returnType}}}{{/returnType}}
+   * @return a {@code {{{returnType}}}}{{/returnType}}
    * @throws ApiException if fails to make API call
    {{#isDeprecated}}
    * @deprecated

diff --git a/modules/openapi-generator/src/main/resources/Java/libraries/resteasy/pom.mustache b/modules/openapi-generator/src/main/resources/Java/libraries/resteasy/pom.mustache
@@ -134,6 +134,14 @@
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-javadoc-plugin</artifactId>
                 <version>2.10.4</version>
+                <executions>
+                    <execution>
+                        <id>attach-javadocs</id>
+                        <goals>
+                            <goal>jar</goal>
+                        </goals>
+                    </execution>
+                </executions>
             </plugin>
         </plugins>
     </build>

diff --git a/samples/client/petstore/java/resteasy/pom.xml b/samples/client/petstore/java/resteasy/pom.xml
@@ -128,6 +128,14 @@
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-javadoc-plugin</artifactId>
                 <version>2.10.4</version>
+                <executions>
+                    <execution>
+                        <id>attach-javadocs</id>
+                        <goals>
+                            <goal>jar</goal>
+                        </goals>
+                    </execution>
+                </executions>
             </plugin>
         </plugins>
     </build>