From ec2ed98269cec542a2fc01c963976c89f86123bf Mon Sep 17 00:00:00 2001
From: William Cheng <wing328hk@gmail.com>
Date: Sun, 24 Oct 2021 12:19:20 +0800
Subject: [PATCH] better comment/docstrings in jersey2 apiclient (#10668)

---
 .../Java/libraries/jersey2/ApiClient.mustache | 121 ++++++++++++++++--
 .../org/openapitools/client/ApiClient.java    | 121 ++++++++++++++++--
 .../org/openapitools/client/ApiClient.java    | 121 ++++++++++++++++--
 .../org/openapitools/client/ApiClient.java    | 115 +++++++++++++++--
 .../org/openapitools/client/ApiClient.java    | 115 +++++++++++++++--
 .../org/openapitools/client/ApiClient.java    | 121 ++++++++++++++++--
 6 files changed, 654 insertions(+), 60 deletions(-)

diff --git a/modules/openapi-generator/src/main/resources/Java/libraries/jersey2/ApiClient.mustache b/modules/openapi-generator/src/main/resources/Java/libraries/jersey2/ApiClient.mustache
index bb78ec3a458..286838dcff4 100644
--- a/modules/openapi-generator/src/main/resources/Java/libraries/jersey2/ApiClient.mustache
+++ b/modules/openapi-generator/src/main/resources/Java/libraries/jersey2/ApiClient.mustache
@@ -79,6 +79,9 @@ import {{invokerPackage}}.auth.ApiKeyAuth;
 import {{invokerPackage}}.auth.OAuth;
 {{/hasOAuthMethods}}
 
+/**
+ * <p>ApiClient class.</p>
+ */
 {{>generatedAnnotation}}
 public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
   protected Map<String, String> defaultHeaderMap = new HashMap<String, String>();
@@ -250,10 +253,21 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
     return json;
   }
 
+  /**
+   * <p>Getter for the field <code>httpClient</code>.</p>
+   *
+   * @return a {@link javax.ws.rs.client.Client} object.
+   */
   public Client getHttpClient() {
     return httpClient;
   }
 
+  /**
+   * <p>Setter for the field <code>httpClient</code>.</p>
+   *
+   * @param httpClient a {@link javax.ws.rs.client.Client} object.
+   * @return a {@link org.openapitools.client.ApiClient} object.
+   */
   public ApiClient setHttpClient(Client httpClient) {
     this.httpClient = httpClient;
     return this;
@@ -272,6 +286,7 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
    * Sets the base URL to the location where the OpenAPI document is being served.
    *
    * @param basePath The base URL to the target host.
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setBasePath(String basePath) {
     this.basePath = basePath;
@@ -281,30 +296,63 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
     return this;
   }
 
+  /**
+   * <p>Getter for the field <code>servers</code>.</p>
+   *
+   * @return a {@link java.util.List} of servers.
+   */
   public List<ServerConfiguration> getServers() {
     return servers;
   }
 
+  /**
+   * <p>Setter for the field <code>servers</code>.</p>
+   *
+   * @param servers a {@link java.util.List} of servers.
+   * @return a {@link org.openapitools.client.ApiClient} object.
+   */
   public ApiClient setServers(List<ServerConfiguration> servers) {
     this.servers = servers;
     updateBasePath();
     return this;
   }
 
+  /**
+   * <p>Getter for the field <code>serverIndex</code>.</p>
+   *
+   * @return a {@link java.lang.Integer} object.
+   */
   public Integer getServerIndex() {
     return serverIndex;
   }
 
+  /**
+   * <p>Setter for the field <code>serverIndex</code>.</p>
+   *
+   * @param serverIndex the server index
+   * @return a {@link org.openapitools.client.ApiClient} object.
+   */
   public ApiClient setServerIndex(Integer serverIndex) {
     this.serverIndex = serverIndex;
     updateBasePath();
     return this;
   }
 
+  /**
+   * <p>Getter for the field <code>serverVariables</code>.</p>
+   *
+   * @return a {@link java.util.Map} of server variables.
+   */
   public Map<String, String> getServerVariables() {
     return serverVariables;
   }
 
+  /**
+   * <p>Setter for the field <code>serverVariables</code>.</p>
+   *
+   * @param serverVariables a {@link java.util.Map} of server variables.
+   * @return a {@link org.openapitools.client.ApiClient} object.
+   */
   public ApiClient setServerVariables(Map<String, String> serverVariables) {
     this.serverVariables = serverVariables;
     updateBasePath();
@@ -350,6 +398,7 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
    * Helper method to set username for the first HTTP basic authentication.
    *
    * @param username Username
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setUsername(String username) {
     for (Authentication auth : authentications.values()) {
@@ -365,6 +414,7 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
    * Helper method to set password for the first HTTP basic authentication.
    *
    * @param password Password
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setPassword(String password) {
     for (Authentication auth : authentications.values()) {
@@ -380,6 +430,7 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
    * Helper method to set API key value for the first API key authentication.
    *
    * @param apiKey API key
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setApiKey(String apiKey) {
     for (Authentication auth : authentications.values()) {
@@ -395,6 +446,7 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
    * Helper method to configure authentications which respects aliases of API keys.
    *
    * @param secrets Hash map from authentication name to its secret.
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient configureApiKeys(Map<String, String> secrets) {
     for (Map.Entry<String, Authentication> authEntry : authentications.entrySet()) {
@@ -415,6 +467,7 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
    * Helper method to set API key prefix for the first API key authentication.
    *
    * @param apiKeyPrefix API key prefix
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setApiKeyPrefix(String apiKeyPrefix) {
     for (Authentication auth : authentications.values()) {
@@ -430,6 +483,7 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
    * Helper method to set bearer token for the first Bearer authentication.
    *
    * @param bearerToken Bearer token
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setBearerToken(String bearerToken) {
     for (Authentication auth : authentications.values()) {
@@ -441,11 +495,12 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
     throw new RuntimeException("No Bearer authentication configured!");
   }
 
-
   {{#hasOAuthMethods}}
   /**
    * Helper method to set access token for the first OAuth2 authentication.
+   *
    * @param accessToken Access token
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setAccessToken(String accessToken) {
     for (Authentication auth : authentications.values()) {
@@ -462,6 +517,7 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
    *
    * @param clientId the client ID
    * @param clientSecret the client secret
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setOauthCredentials(String clientId, String clientSecret) {
     for (Authentication auth : authentications.values()) {
@@ -478,6 +534,7 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
    *
    * @param username the user name
    * @param password the user password
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setOauthPasswordFlow(String username, String password) {
     for (Authentication auth : authentications.values()) {
@@ -493,6 +550,7 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
    * Helper method to set the authorization code flow for the first OAuth2 authentication.
    *
    * @param code the authorization code
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setOauthAuthorizationCodeFlow(String code) {
     for (Authentication auth : authentications.values()) {
@@ -508,6 +566,7 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
    * Helper method to set the scopes for the first OAuth2 authentication.
    *
    * @param scope the oauth scope
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setOauthScope(String scope) {
     for (Authentication auth : authentications.values()) {
@@ -522,8 +581,9 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
   {{/hasOAuthMethods}}
   /**
    * Set the User-Agent header's value (by adding to the default header map).
+   *
    * @param userAgent Http user agent
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setUserAgent(String userAgent) {
     this.userAgent = userAgent;
@@ -533,6 +593,7 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
 
   /**
    * Get the User-Agent header's value.
+   *
    * @return User-Agent string
    */
   public String getUserAgent(){
@@ -544,7 +605,7 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
    *
    * @param key The header's key
    * @param value The header's value
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient addDefaultHeader(String key, String value) {
     defaultHeaderMap.put(key, value);
@@ -556,7 +617,7 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
    *
    * @param key The cookie's key
    * @param value The cookie's value
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient addDefaultCookie(String key, String value) {
     defaultCookieMap.put(key, value);
@@ -565,6 +626,7 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
 
   /**
    * Gets the client config.
+   *
    * @return Client config
    */
   public ClientConfig getClientConfig() {
@@ -575,7 +637,7 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
    * Set the client config.
    *
    * @param clientConfig Set the client config
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setClientConfig(ClientConfig clientConfig) {
     this.clientConfig = clientConfig;
@@ -586,6 +648,7 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
 
   /**
    * Check that whether debugging is enabled for this API client.
+   *
    * @return True if debugging is switched on
    */
   public boolean isDebugging() {
@@ -596,7 +659,7 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
    * Enable/disable debugging for this API client.
    *
    * @param debugging To enable (true) or disable (false) debugging
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setDebugging(boolean debugging) {
     this.debugging = debugging;
@@ -618,8 +681,9 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
 
   /**
    * Set temp folder path
+   *
    * @param tempFolderPath Temp folder path
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setTempFolderPath(String tempFolderPath) {
     this.tempFolderPath = tempFolderPath;
@@ -628,6 +692,7 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
 
   /**
    * Connect timeout (in milliseconds).
+   *
    * @return Connection timeout
    */
   public int getConnectTimeout() {
@@ -638,8 +703,9 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
    * Set the connect timeout (in milliseconds).
    * A value of 0 means no timeout, otherwise values must be between 1 and
    * {@link Integer#MAX_VALUE}.
+   *
    * @param connectionTimeout Connection timeout in milliseconds
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setConnectTimeout(int connectionTimeout) {
     this.connectionTimeout = connectionTimeout;
@@ -649,6 +715,7 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
 
   /**
    * read timeout (in milliseconds).
+   *
    * @return Read timeout
    */
   public int getReadTimeout() {
@@ -659,8 +726,9 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
    * Set the read timeout (in milliseconds).
    * A value of 0 means no timeout, otherwise values must be between 1 and
    * {@link Integer#MAX_VALUE}.
+   *
    * @param readTimeout Read timeout in milliseconds
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setReadTimeout(int readTimeout) {
     this.readTimeout = readTimeout;
@@ -670,6 +738,7 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
 
   /**
    * Get the date format used to parse/format date parameters.
+   *
    * @return Date format
    */
   public DateFormat getDateFormat() {
@@ -678,8 +747,9 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
 
   /**
    * Set the date format used to parse/format date parameters.
+   *
    * @param dateFormat Date format
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setDateFormat(DateFormat dateFormat) {
     this.dateFormat = dateFormat;
@@ -690,6 +760,7 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
 
   /**
    * Parse the given string into Date object.
+   *
    * @param str String
    * @return Date
    */
@@ -703,6 +774,7 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
 
   /**
    * Format the given Date object into string.
+   *
    * @param date Date
    * @return Date in string format
    */
@@ -712,6 +784,7 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
 
   /**
    * Format the given parameter object into string.
+   *
    * @param param Object
    * @return Object in string format
    */
@@ -738,6 +811,7 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
 
   /*
    * Format to {@code Pair} objects.
+   *
    * @param collectionFormat Collection format
    * @param name Name
    * @param value Value
@@ -804,6 +878,7 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
    *   APPLICATION/JSON
    *   application/vnd.company+json
    * "* / *" is also default to JSON
+   *
    * @param mime MIME
    * @return True if the MIME type is JSON
    */
@@ -856,6 +931,7 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
 
   /**
    * Escape the given string to be used as URL query value.
+   *
    * @param str String
    * @return Escaped string
    */
@@ -870,6 +946,7 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
   /**
    * Serialize the given Java object into string entity according the given
    * Content-Type (only JSON is supported for now).
+   *
    * @param obj Object
    * @param formParams Form parameters
    * @param contentType Context type
@@ -920,6 +997,7 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
   /**
    * Serialize the given Java object into string according the given
    * Content-Type (only JSON, HTTP form is supported for now).
+   *
    * @param obj Object
    * @param formParams Form parameters
    * @param contentType Context type
@@ -956,6 +1034,7 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
 
   /**
    * Deserialize response body to Java object according to the Content-Type.
+   *
    * @param <T> Type
    * @param response Response
    * @param returnType Return type
@@ -990,6 +1069,7 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
 
   /**
    * Download file from the given response.
+   *
    * @param response Response
    * @return File
    * @throws ApiException If fail to read file content from response and write to disk
@@ -1004,6 +1084,13 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
     }
   }
 
+  /**
+   * <p>Prepare the file for download from the response.</p>
+   *
+   * @param response a {@link javax.ws.rs.core.Response} object.
+   * @return a {@link java.io.File} object.
+   * @throws java.io.IOException if any.
+   */
   public File prepareDownloadFile(Response response) throws IOException {
     String filename = null;
     String contentDisposition = (String) response.getHeaders().getFirst("Content-Disposition");
@@ -1226,6 +1313,7 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
 
   /**
    * Build the Client used to make HTTP requests.
+   *
    * @return Client
    */
   protected Client buildHttpClient() {
@@ -1240,6 +1328,7 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
 
   /**
    * Get the default client config.
+   *
    * @return Client config
    */
   public ClientConfig getDefaultClientConfig() {
@@ -1276,6 +1365,8 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
    *
    * To completely disable certificate validation (at your own risk), you can
    * override this method and invoke disableCertificateValidation(clientBuilder).
+   *
+   * @param clientBuilder a {@link javax.ws.rs.client.ClientBuilder} object.
    */
   protected void customizeClientBuilder(ClientBuilder clientBuilder) {
     // No-op extension point
@@ -1286,6 +1377,10 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
    *
    * Please note that trusting all certificates is extremely risky.
    * This may be useful in a development environment with self-signed certificates.
+   *
+   * @param clientBuilder a {@link javax.ws.rs.client.ClientBuilder} object.
+   * @throws java.security.KeyManagementException if any.
+   * @throws java.security.NoSuchAlgorithmException if any.
    */
   protected void disableCertificateValidation(ClientBuilder clientBuilder) throws KeyManagementException, NoSuchAlgorithmException {
     TrustManager[] trustAllCerts = new X509TrustManager[] {
@@ -1307,6 +1402,12 @@ public class ApiClient{{#jsr310}} extends JavaTimeFormatter{{/jsr310}} {
     clientBuilder.sslContext(sslContext);
   }
 
+  /**
+   * <p>Build the response headers.</p>
+   *
+   * @param response a {@link javax.ws.rs.core.Response} object.
+   * @return a {@link java.util.Map} of response headers.
+   */
   protected Map<String, List<String>> buildResponseHeaders(Response response) {
     Map<String, List<String>> responseHeaders = new HashMap<String, List<String>>();
     for (Entry<String, List<Object>> entry: response.getHeaders().entrySet()) {
diff --git a/samples/client/petstore/java/jersey2-java8-localdatetime/src/main/java/org/openapitools/client/ApiClient.java b/samples/client/petstore/java/jersey2-java8-localdatetime/src/main/java/org/openapitools/client/ApiClient.java
index 9b3aa790f3d..5f4cb48efe2 100644
--- a/samples/client/petstore/java/jersey2-java8-localdatetime/src/main/java/org/openapitools/client/ApiClient.java
+++ b/samples/client/petstore/java/jersey2-java8-localdatetime/src/main/java/org/openapitools/client/ApiClient.java
@@ -65,6 +65,9 @@ import org.openapitools.client.auth.HttpBearerAuth;
 import org.openapitools.client.auth.ApiKeyAuth;
 import org.openapitools.client.auth.OAuth;
 
+/**
+ * <p>ApiClient class.</p>
+ */
 @javax.annotation.Generated(value = "org.openapitools.codegen.languages.JavaClientCodegen")
 public class ApiClient extends JavaTimeFormatter {
   protected Map<String, String> defaultHeaderMap = new HashMap<String, String>();
@@ -172,10 +175,21 @@ public class ApiClient extends JavaTimeFormatter {
     return json;
   }
 
+  /**
+   * <p>Getter for the field <code>httpClient</code>.</p>
+   *
+   * @return a {@link javax.ws.rs.client.Client} object.
+   */
   public Client getHttpClient() {
     return httpClient;
   }
 
+  /**
+   * <p>Setter for the field <code>httpClient</code>.</p>
+   *
+   * @param httpClient a {@link javax.ws.rs.client.Client} object.
+   * @return a {@link org.openapitools.client.ApiClient} object.
+   */
   public ApiClient setHttpClient(Client httpClient) {
     this.httpClient = httpClient;
     return this;
@@ -194,6 +208,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Sets the base URL to the location where the OpenAPI document is being served.
    *
    * @param basePath The base URL to the target host.
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setBasePath(String basePath) {
     this.basePath = basePath;
@@ -201,30 +216,63 @@ public class ApiClient extends JavaTimeFormatter {
     return this;
   }
 
+  /**
+   * <p>Getter for the field <code>servers</code>.</p>
+   *
+   * @return a {@link java.util.List} of servers.
+   */
   public List<ServerConfiguration> getServers() {
     return servers;
   }
 
+  /**
+   * <p>Setter for the field <code>servers</code>.</p>
+   *
+   * @param servers a {@link java.util.List} of servers.
+   * @return a {@link org.openapitools.client.ApiClient} object.
+   */
   public ApiClient setServers(List<ServerConfiguration> servers) {
     this.servers = servers;
     updateBasePath();
     return this;
   }
 
+  /**
+   * <p>Getter for the field <code>serverIndex</code>.</p>
+   *
+   * @return a {@link java.lang.Integer} object.
+   */
   public Integer getServerIndex() {
     return serverIndex;
   }
 
+  /**
+   * <p>Setter for the field <code>serverIndex</code>.</p>
+   *
+   * @param serverIndex the server index
+   * @return a {@link org.openapitools.client.ApiClient} object.
+   */
   public ApiClient setServerIndex(Integer serverIndex) {
     this.serverIndex = serverIndex;
     updateBasePath();
     return this;
   }
 
+  /**
+   * <p>Getter for the field <code>serverVariables</code>.</p>
+   *
+   * @return a {@link java.util.Map} of server variables.
+   */
   public Map<String, String> getServerVariables() {
     return serverVariables;
   }
 
+  /**
+   * <p>Setter for the field <code>serverVariables</code>.</p>
+   *
+   * @param serverVariables a {@link java.util.Map} of server variables.
+   * @return a {@link org.openapitools.client.ApiClient} object.
+   */
   public ApiClient setServerVariables(Map<String, String> serverVariables) {
     this.serverVariables = serverVariables;
     updateBasePath();
@@ -268,6 +316,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Helper method to set username for the first HTTP basic authentication.
    *
    * @param username Username
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setUsername(String username) {
     for (Authentication auth : authentications.values()) {
@@ -283,6 +332,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Helper method to set password for the first HTTP basic authentication.
    *
    * @param password Password
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setPassword(String password) {
     for (Authentication auth : authentications.values()) {
@@ -298,6 +348,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Helper method to set API key value for the first API key authentication.
    *
    * @param apiKey API key
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setApiKey(String apiKey) {
     for (Authentication auth : authentications.values()) {
@@ -313,6 +364,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Helper method to configure authentications which respects aliases of API keys.
    *
    * @param secrets Hash map from authentication name to its secret.
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient configureApiKeys(Map<String, String> secrets) {
     for (Map.Entry<String, Authentication> authEntry : authentications.entrySet()) {
@@ -333,6 +385,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Helper method to set API key prefix for the first API key authentication.
    *
    * @param apiKeyPrefix API key prefix
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setApiKeyPrefix(String apiKeyPrefix) {
     for (Authentication auth : authentications.values()) {
@@ -348,6 +401,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Helper method to set bearer token for the first Bearer authentication.
    *
    * @param bearerToken Bearer token
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setBearerToken(String bearerToken) {
     for (Authentication auth : authentications.values()) {
@@ -359,10 +413,11 @@ public class ApiClient extends JavaTimeFormatter {
     throw new RuntimeException("No Bearer authentication configured!");
   }
 
-
   /**
    * Helper method to set access token for the first OAuth2 authentication.
+   *
    * @param accessToken Access token
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setAccessToken(String accessToken) {
     for (Authentication auth : authentications.values()) {
@@ -379,6 +434,7 @@ public class ApiClient extends JavaTimeFormatter {
    *
    * @param clientId the client ID
    * @param clientSecret the client secret
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setOauthCredentials(String clientId, String clientSecret) {
     for (Authentication auth : authentications.values()) {
@@ -395,6 +451,7 @@ public class ApiClient extends JavaTimeFormatter {
    *
    * @param username the user name
    * @param password the user password
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setOauthPasswordFlow(String username, String password) {
     for (Authentication auth : authentications.values()) {
@@ -410,6 +467,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Helper method to set the authorization code flow for the first OAuth2 authentication.
    *
    * @param code the authorization code
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setOauthAuthorizationCodeFlow(String code) {
     for (Authentication auth : authentications.values()) {
@@ -425,6 +483,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Helper method to set the scopes for the first OAuth2 authentication.
    *
    * @param scope the oauth scope
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setOauthScope(String scope) {
     for (Authentication auth : authentications.values()) {
@@ -438,8 +497,9 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Set the User-Agent header's value (by adding to the default header map).
+   *
    * @param userAgent Http user agent
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setUserAgent(String userAgent) {
     this.userAgent = userAgent;
@@ -449,6 +509,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Get the User-Agent header's value.
+   *
    * @return User-Agent string
    */
   public String getUserAgent(){
@@ -460,7 +521,7 @@ public class ApiClient extends JavaTimeFormatter {
    *
    * @param key The header's key
    * @param value The header's value
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient addDefaultHeader(String key, String value) {
     defaultHeaderMap.put(key, value);
@@ -472,7 +533,7 @@ public class ApiClient extends JavaTimeFormatter {
    *
    * @param key The cookie's key
    * @param value The cookie's value
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient addDefaultCookie(String key, String value) {
     defaultCookieMap.put(key, value);
@@ -481,6 +542,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Gets the client config.
+   *
    * @return Client config
    */
   public ClientConfig getClientConfig() {
@@ -491,7 +553,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Set the client config.
    *
    * @param clientConfig Set the client config
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setClientConfig(ClientConfig clientConfig) {
     this.clientConfig = clientConfig;
@@ -502,6 +564,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Check that whether debugging is enabled for this API client.
+   *
    * @return True if debugging is switched on
    */
   public boolean isDebugging() {
@@ -512,7 +575,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Enable/disable debugging for this API client.
    *
    * @param debugging To enable (true) or disable (false) debugging
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setDebugging(boolean debugging) {
     this.debugging = debugging;
@@ -534,8 +597,9 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Set temp folder path
+   *
    * @param tempFolderPath Temp folder path
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setTempFolderPath(String tempFolderPath) {
     this.tempFolderPath = tempFolderPath;
@@ -544,6 +608,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Connect timeout (in milliseconds).
+   *
    * @return Connection timeout
    */
   public int getConnectTimeout() {
@@ -554,8 +619,9 @@ public class ApiClient extends JavaTimeFormatter {
    * Set the connect timeout (in milliseconds).
    * A value of 0 means no timeout, otherwise values must be between 1 and
    * {@link Integer#MAX_VALUE}.
+   *
    * @param connectionTimeout Connection timeout in milliseconds
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setConnectTimeout(int connectionTimeout) {
     this.connectionTimeout = connectionTimeout;
@@ -565,6 +631,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * read timeout (in milliseconds).
+   *
    * @return Read timeout
    */
   public int getReadTimeout() {
@@ -575,8 +642,9 @@ public class ApiClient extends JavaTimeFormatter {
    * Set the read timeout (in milliseconds).
    * A value of 0 means no timeout, otherwise values must be between 1 and
    * {@link Integer#MAX_VALUE}.
+   *
    * @param readTimeout Read timeout in milliseconds
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setReadTimeout(int readTimeout) {
     this.readTimeout = readTimeout;
@@ -586,6 +654,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Get the date format used to parse/format date parameters.
+   *
    * @return Date format
    */
   public DateFormat getDateFormat() {
@@ -594,8 +663,9 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Set the date format used to parse/format date parameters.
+   *
    * @param dateFormat Date format
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setDateFormat(DateFormat dateFormat) {
     this.dateFormat = dateFormat;
@@ -606,6 +676,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Parse the given string into Date object.
+   *
    * @param str String
    * @return Date
    */
@@ -619,6 +690,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Format the given Date object into string.
+   *
    * @param date Date
    * @return Date in string format
    */
@@ -628,6 +700,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Format the given parameter object into string.
+   *
    * @param param Object
    * @return Object in string format
    */
@@ -654,6 +727,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /*
    * Format to {@code Pair} objects.
+   *
    * @param collectionFormat Collection format
    * @param name Name
    * @param value Value
@@ -720,6 +794,7 @@ public class ApiClient extends JavaTimeFormatter {
    *   APPLICATION/JSON
    *   application/vnd.company+json
    * "* / *" is also default to JSON
+   *
    * @param mime MIME
    * @return True if the MIME type is JSON
    */
@@ -772,6 +847,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Escape the given string to be used as URL query value.
+   *
    * @param str String
    * @return Escaped string
    */
@@ -786,6 +862,7 @@ public class ApiClient extends JavaTimeFormatter {
   /**
    * Serialize the given Java object into string entity according the given
    * Content-Type (only JSON is supported for now).
+   *
    * @param obj Object
    * @param formParams Form parameters
    * @param contentType Context type
@@ -836,6 +913,7 @@ public class ApiClient extends JavaTimeFormatter {
   /**
    * Serialize the given Java object into string according the given
    * Content-Type (only JSON, HTTP form is supported for now).
+   *
    * @param obj Object
    * @param formParams Form parameters
    * @param contentType Context type
@@ -872,6 +950,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Deserialize response body to Java object according to the Content-Type.
+   *
    * @param <T> Type
    * @param response Response
    * @param returnType Return type
@@ -906,6 +985,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Download file from the given response.
+   *
    * @param response Response
    * @return File
    * @throws ApiException If fail to read file content from response and write to disk
@@ -920,6 +1000,13 @@ public class ApiClient extends JavaTimeFormatter {
     }
   }
 
+  /**
+   * <p>Prepare the file for download from the response.</p>
+   *
+   * @param response a {@link javax.ws.rs.core.Response} object.
+   * @return a {@link java.io.File} object.
+   * @throws java.io.IOException if any.
+   */
   public File prepareDownloadFile(Response response) throws IOException {
     String filename = null;
     String contentDisposition = (String) response.getHeaders().getFirst("Content-Disposition");
@@ -1140,6 +1227,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Build the Client used to make HTTP requests.
+   *
    * @return Client
    */
   protected Client buildHttpClient() {
@@ -1154,6 +1242,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Get the default client config.
+   *
    * @return Client config
    */
   public ClientConfig getDefaultClientConfig() {
@@ -1190,6 +1279,8 @@ public class ApiClient extends JavaTimeFormatter {
    *
    * To completely disable certificate validation (at your own risk), you can
    * override this method and invoke disableCertificateValidation(clientBuilder).
+   *
+   * @param clientBuilder a {@link javax.ws.rs.client.ClientBuilder} object.
    */
   protected void customizeClientBuilder(ClientBuilder clientBuilder) {
     // No-op extension point
@@ -1200,6 +1291,10 @@ public class ApiClient extends JavaTimeFormatter {
    *
    * Please note that trusting all certificates is extremely risky.
    * This may be useful in a development environment with self-signed certificates.
+   *
+   * @param clientBuilder a {@link javax.ws.rs.client.ClientBuilder} object.
+   * @throws java.security.KeyManagementException if any.
+   * @throws java.security.NoSuchAlgorithmException if any.
    */
   protected void disableCertificateValidation(ClientBuilder clientBuilder) throws KeyManagementException, NoSuchAlgorithmException {
     TrustManager[] trustAllCerts = new X509TrustManager[] {
@@ -1221,6 +1316,12 @@ public class ApiClient extends JavaTimeFormatter {
     clientBuilder.sslContext(sslContext);
   }
 
+  /**
+   * <p>Build the response headers.</p>
+   *
+   * @param response a {@link javax.ws.rs.core.Response} object.
+   * @return a {@link java.util.Map} of response headers.
+   */
   protected Map<String, List<String>> buildResponseHeaders(Response response) {
     Map<String, List<String>> responseHeaders = new HashMap<String, List<String>>();
     for (Entry<String, List<Object>> entry: response.getHeaders().entrySet()) {
diff --git a/samples/client/petstore/java/jersey2-java8/src/main/java/org/openapitools/client/ApiClient.java b/samples/client/petstore/java/jersey2-java8/src/main/java/org/openapitools/client/ApiClient.java
index 9b3aa790f3d..5f4cb48efe2 100644
--- a/samples/client/petstore/java/jersey2-java8/src/main/java/org/openapitools/client/ApiClient.java
+++ b/samples/client/petstore/java/jersey2-java8/src/main/java/org/openapitools/client/ApiClient.java
@@ -65,6 +65,9 @@ import org.openapitools.client.auth.HttpBearerAuth;
 import org.openapitools.client.auth.ApiKeyAuth;
 import org.openapitools.client.auth.OAuth;
 
+/**
+ * <p>ApiClient class.</p>
+ */
 @javax.annotation.Generated(value = "org.openapitools.codegen.languages.JavaClientCodegen")
 public class ApiClient extends JavaTimeFormatter {
   protected Map<String, String> defaultHeaderMap = new HashMap<String, String>();
@@ -172,10 +175,21 @@ public class ApiClient extends JavaTimeFormatter {
     return json;
   }
 
+  /**
+   * <p>Getter for the field <code>httpClient</code>.</p>
+   *
+   * @return a {@link javax.ws.rs.client.Client} object.
+   */
   public Client getHttpClient() {
     return httpClient;
   }
 
+  /**
+   * <p>Setter for the field <code>httpClient</code>.</p>
+   *
+   * @param httpClient a {@link javax.ws.rs.client.Client} object.
+   * @return a {@link org.openapitools.client.ApiClient} object.
+   */
   public ApiClient setHttpClient(Client httpClient) {
     this.httpClient = httpClient;
     return this;
@@ -194,6 +208,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Sets the base URL to the location where the OpenAPI document is being served.
    *
    * @param basePath The base URL to the target host.
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setBasePath(String basePath) {
     this.basePath = basePath;
@@ -201,30 +216,63 @@ public class ApiClient extends JavaTimeFormatter {
     return this;
   }
 
+  /**
+   * <p>Getter for the field <code>servers</code>.</p>
+   *
+   * @return a {@link java.util.List} of servers.
+   */
   public List<ServerConfiguration> getServers() {
     return servers;
   }
 
+  /**
+   * <p>Setter for the field <code>servers</code>.</p>
+   *
+   * @param servers a {@link java.util.List} of servers.
+   * @return a {@link org.openapitools.client.ApiClient} object.
+   */
   public ApiClient setServers(List<ServerConfiguration> servers) {
     this.servers = servers;
     updateBasePath();
     return this;
   }
 
+  /**
+   * <p>Getter for the field <code>serverIndex</code>.</p>
+   *
+   * @return a {@link java.lang.Integer} object.
+   */
   public Integer getServerIndex() {
     return serverIndex;
   }
 
+  /**
+   * <p>Setter for the field <code>serverIndex</code>.</p>
+   *
+   * @param serverIndex the server index
+   * @return a {@link org.openapitools.client.ApiClient} object.
+   */
   public ApiClient setServerIndex(Integer serverIndex) {
     this.serverIndex = serverIndex;
     updateBasePath();
     return this;
   }
 
+  /**
+   * <p>Getter for the field <code>serverVariables</code>.</p>
+   *
+   * @return a {@link java.util.Map} of server variables.
+   */
   public Map<String, String> getServerVariables() {
     return serverVariables;
   }
 
+  /**
+   * <p>Setter for the field <code>serverVariables</code>.</p>
+   *
+   * @param serverVariables a {@link java.util.Map} of server variables.
+   * @return a {@link org.openapitools.client.ApiClient} object.
+   */
   public ApiClient setServerVariables(Map<String, String> serverVariables) {
     this.serverVariables = serverVariables;
     updateBasePath();
@@ -268,6 +316,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Helper method to set username for the first HTTP basic authentication.
    *
    * @param username Username
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setUsername(String username) {
     for (Authentication auth : authentications.values()) {
@@ -283,6 +332,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Helper method to set password for the first HTTP basic authentication.
    *
    * @param password Password
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setPassword(String password) {
     for (Authentication auth : authentications.values()) {
@@ -298,6 +348,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Helper method to set API key value for the first API key authentication.
    *
    * @param apiKey API key
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setApiKey(String apiKey) {
     for (Authentication auth : authentications.values()) {
@@ -313,6 +364,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Helper method to configure authentications which respects aliases of API keys.
    *
    * @param secrets Hash map from authentication name to its secret.
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient configureApiKeys(Map<String, String> secrets) {
     for (Map.Entry<String, Authentication> authEntry : authentications.entrySet()) {
@@ -333,6 +385,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Helper method to set API key prefix for the first API key authentication.
    *
    * @param apiKeyPrefix API key prefix
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setApiKeyPrefix(String apiKeyPrefix) {
     for (Authentication auth : authentications.values()) {
@@ -348,6 +401,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Helper method to set bearer token for the first Bearer authentication.
    *
    * @param bearerToken Bearer token
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setBearerToken(String bearerToken) {
     for (Authentication auth : authentications.values()) {
@@ -359,10 +413,11 @@ public class ApiClient extends JavaTimeFormatter {
     throw new RuntimeException("No Bearer authentication configured!");
   }
 
-
   /**
    * Helper method to set access token for the first OAuth2 authentication.
+   *
    * @param accessToken Access token
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setAccessToken(String accessToken) {
     for (Authentication auth : authentications.values()) {
@@ -379,6 +434,7 @@ public class ApiClient extends JavaTimeFormatter {
    *
    * @param clientId the client ID
    * @param clientSecret the client secret
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setOauthCredentials(String clientId, String clientSecret) {
     for (Authentication auth : authentications.values()) {
@@ -395,6 +451,7 @@ public class ApiClient extends JavaTimeFormatter {
    *
    * @param username the user name
    * @param password the user password
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setOauthPasswordFlow(String username, String password) {
     for (Authentication auth : authentications.values()) {
@@ -410,6 +467,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Helper method to set the authorization code flow for the first OAuth2 authentication.
    *
    * @param code the authorization code
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setOauthAuthorizationCodeFlow(String code) {
     for (Authentication auth : authentications.values()) {
@@ -425,6 +483,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Helper method to set the scopes for the first OAuth2 authentication.
    *
    * @param scope the oauth scope
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setOauthScope(String scope) {
     for (Authentication auth : authentications.values()) {
@@ -438,8 +497,9 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Set the User-Agent header's value (by adding to the default header map).
+   *
    * @param userAgent Http user agent
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setUserAgent(String userAgent) {
     this.userAgent = userAgent;
@@ -449,6 +509,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Get the User-Agent header's value.
+   *
    * @return User-Agent string
    */
   public String getUserAgent(){
@@ -460,7 +521,7 @@ public class ApiClient extends JavaTimeFormatter {
    *
    * @param key The header's key
    * @param value The header's value
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient addDefaultHeader(String key, String value) {
     defaultHeaderMap.put(key, value);
@@ -472,7 +533,7 @@ public class ApiClient extends JavaTimeFormatter {
    *
    * @param key The cookie's key
    * @param value The cookie's value
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient addDefaultCookie(String key, String value) {
     defaultCookieMap.put(key, value);
@@ -481,6 +542,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Gets the client config.
+   *
    * @return Client config
    */
   public ClientConfig getClientConfig() {
@@ -491,7 +553,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Set the client config.
    *
    * @param clientConfig Set the client config
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setClientConfig(ClientConfig clientConfig) {
     this.clientConfig = clientConfig;
@@ -502,6 +564,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Check that whether debugging is enabled for this API client.
+   *
    * @return True if debugging is switched on
    */
   public boolean isDebugging() {
@@ -512,7 +575,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Enable/disable debugging for this API client.
    *
    * @param debugging To enable (true) or disable (false) debugging
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setDebugging(boolean debugging) {
     this.debugging = debugging;
@@ -534,8 +597,9 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Set temp folder path
+   *
    * @param tempFolderPath Temp folder path
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setTempFolderPath(String tempFolderPath) {
     this.tempFolderPath = tempFolderPath;
@@ -544,6 +608,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Connect timeout (in milliseconds).
+   *
    * @return Connection timeout
    */
   public int getConnectTimeout() {
@@ -554,8 +619,9 @@ public class ApiClient extends JavaTimeFormatter {
    * Set the connect timeout (in milliseconds).
    * A value of 0 means no timeout, otherwise values must be between 1 and
    * {@link Integer#MAX_VALUE}.
+   *
    * @param connectionTimeout Connection timeout in milliseconds
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setConnectTimeout(int connectionTimeout) {
     this.connectionTimeout = connectionTimeout;
@@ -565,6 +631,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * read timeout (in milliseconds).
+   *
    * @return Read timeout
    */
   public int getReadTimeout() {
@@ -575,8 +642,9 @@ public class ApiClient extends JavaTimeFormatter {
    * Set the read timeout (in milliseconds).
    * A value of 0 means no timeout, otherwise values must be between 1 and
    * {@link Integer#MAX_VALUE}.
+   *
    * @param readTimeout Read timeout in milliseconds
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setReadTimeout(int readTimeout) {
     this.readTimeout = readTimeout;
@@ -586,6 +654,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Get the date format used to parse/format date parameters.
+   *
    * @return Date format
    */
   public DateFormat getDateFormat() {
@@ -594,8 +663,9 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Set the date format used to parse/format date parameters.
+   *
    * @param dateFormat Date format
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setDateFormat(DateFormat dateFormat) {
     this.dateFormat = dateFormat;
@@ -606,6 +676,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Parse the given string into Date object.
+   *
    * @param str String
    * @return Date
    */
@@ -619,6 +690,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Format the given Date object into string.
+   *
    * @param date Date
    * @return Date in string format
    */
@@ -628,6 +700,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Format the given parameter object into string.
+   *
    * @param param Object
    * @return Object in string format
    */
@@ -654,6 +727,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /*
    * Format to {@code Pair} objects.
+   *
    * @param collectionFormat Collection format
    * @param name Name
    * @param value Value
@@ -720,6 +794,7 @@ public class ApiClient extends JavaTimeFormatter {
    *   APPLICATION/JSON
    *   application/vnd.company+json
    * "* / *" is also default to JSON
+   *
    * @param mime MIME
    * @return True if the MIME type is JSON
    */
@@ -772,6 +847,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Escape the given string to be used as URL query value.
+   *
    * @param str String
    * @return Escaped string
    */
@@ -786,6 +862,7 @@ public class ApiClient extends JavaTimeFormatter {
   /**
    * Serialize the given Java object into string entity according the given
    * Content-Type (only JSON is supported for now).
+   *
    * @param obj Object
    * @param formParams Form parameters
    * @param contentType Context type
@@ -836,6 +913,7 @@ public class ApiClient extends JavaTimeFormatter {
   /**
    * Serialize the given Java object into string according the given
    * Content-Type (only JSON, HTTP form is supported for now).
+   *
    * @param obj Object
    * @param formParams Form parameters
    * @param contentType Context type
@@ -872,6 +950,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Deserialize response body to Java object according to the Content-Type.
+   *
    * @param <T> Type
    * @param response Response
    * @param returnType Return type
@@ -906,6 +985,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Download file from the given response.
+   *
    * @param response Response
    * @return File
    * @throws ApiException If fail to read file content from response and write to disk
@@ -920,6 +1000,13 @@ public class ApiClient extends JavaTimeFormatter {
     }
   }
 
+  /**
+   * <p>Prepare the file for download from the response.</p>
+   *
+   * @param response a {@link javax.ws.rs.core.Response} object.
+   * @return a {@link java.io.File} object.
+   * @throws java.io.IOException if any.
+   */
   public File prepareDownloadFile(Response response) throws IOException {
     String filename = null;
     String contentDisposition = (String) response.getHeaders().getFirst("Content-Disposition");
@@ -1140,6 +1227,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Build the Client used to make HTTP requests.
+   *
    * @return Client
    */
   protected Client buildHttpClient() {
@@ -1154,6 +1242,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Get the default client config.
+   *
    * @return Client config
    */
   public ClientConfig getDefaultClientConfig() {
@@ -1190,6 +1279,8 @@ public class ApiClient extends JavaTimeFormatter {
    *
    * To completely disable certificate validation (at your own risk), you can
    * override this method and invoke disableCertificateValidation(clientBuilder).
+   *
+   * @param clientBuilder a {@link javax.ws.rs.client.ClientBuilder} object.
    */
   protected void customizeClientBuilder(ClientBuilder clientBuilder) {
     // No-op extension point
@@ -1200,6 +1291,10 @@ public class ApiClient extends JavaTimeFormatter {
    *
    * Please note that trusting all certificates is extremely risky.
    * This may be useful in a development environment with self-signed certificates.
+   *
+   * @param clientBuilder a {@link javax.ws.rs.client.ClientBuilder} object.
+   * @throws java.security.KeyManagementException if any.
+   * @throws java.security.NoSuchAlgorithmException if any.
    */
   protected void disableCertificateValidation(ClientBuilder clientBuilder) throws KeyManagementException, NoSuchAlgorithmException {
     TrustManager[] trustAllCerts = new X509TrustManager[] {
@@ -1221,6 +1316,12 @@ public class ApiClient extends JavaTimeFormatter {
     clientBuilder.sslContext(sslContext);
   }
 
+  /**
+   * <p>Build the response headers.</p>
+   *
+   * @param response a {@link javax.ws.rs.core.Response} object.
+   * @return a {@link java.util.Map} of response headers.
+   */
   protected Map<String, List<String>> buildResponseHeaders(Response response) {
     Map<String, List<String>> responseHeaders = new HashMap<String, List<String>>();
     for (Entry<String, List<Object>> entry: response.getHeaders().entrySet()) {
diff --git a/samples/openapi3/client/extensions/x-auth-id-alias/java/jersey2-java8/src/main/java/org/openapitools/client/ApiClient.java b/samples/openapi3/client/extensions/x-auth-id-alias/java/jersey2-java8/src/main/java/org/openapitools/client/ApiClient.java
index 7c0a3e1ab68..7f844074052 100644
--- a/samples/openapi3/client/extensions/x-auth-id-alias/java/jersey2-java8/src/main/java/org/openapitools/client/ApiClient.java
+++ b/samples/openapi3/client/extensions/x-auth-id-alias/java/jersey2-java8/src/main/java/org/openapitools/client/ApiClient.java
@@ -63,6 +63,9 @@ import org.openapitools.client.auth.HttpBasicAuth;
 import org.openapitools.client.auth.HttpBearerAuth;
 import org.openapitools.client.auth.ApiKeyAuth;
 
+/**
+ * <p>ApiClient class.</p>
+ */
 @javax.annotation.Generated(value = "org.openapitools.codegen.languages.JavaClientCodegen")
 public class ApiClient extends JavaTimeFormatter {
   protected Map<String, String> defaultHeaderMap = new HashMap<String, String>();
@@ -193,10 +196,21 @@ public class ApiClient extends JavaTimeFormatter {
     return json;
   }
 
+  /**
+   * <p>Getter for the field <code>httpClient</code>.</p>
+   *
+   * @return a {@link javax.ws.rs.client.Client} object.
+   */
   public Client getHttpClient() {
     return httpClient;
   }
 
+  /**
+   * <p>Setter for the field <code>httpClient</code>.</p>
+   *
+   * @param httpClient a {@link javax.ws.rs.client.Client} object.
+   * @return a {@link org.openapitools.client.ApiClient} object.
+   */
   public ApiClient setHttpClient(Client httpClient) {
     this.httpClient = httpClient;
     return this;
@@ -215,36 +229,70 @@ public class ApiClient extends JavaTimeFormatter {
    * Sets the base URL to the location where the OpenAPI document is being served.
    *
    * @param basePath The base URL to the target host.
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setBasePath(String basePath) {
     this.basePath = basePath;
     return this;
   }
 
+  /**
+   * <p>Getter for the field <code>servers</code>.</p>
+   *
+   * @return a {@link java.util.List} of servers.
+   */
   public List<ServerConfiguration> getServers() {
     return servers;
   }
 
+  /**
+   * <p>Setter for the field <code>servers</code>.</p>
+   *
+   * @param servers a {@link java.util.List} of servers.
+   * @return a {@link org.openapitools.client.ApiClient} object.
+   */
   public ApiClient setServers(List<ServerConfiguration> servers) {
     this.servers = servers;
     updateBasePath();
     return this;
   }
 
+  /**
+   * <p>Getter for the field <code>serverIndex</code>.</p>
+   *
+   * @return a {@link java.lang.Integer} object.
+   */
   public Integer getServerIndex() {
     return serverIndex;
   }
 
+  /**
+   * <p>Setter for the field <code>serverIndex</code>.</p>
+   *
+   * @param serverIndex the server index
+   * @return a {@link org.openapitools.client.ApiClient} object.
+   */
   public ApiClient setServerIndex(Integer serverIndex) {
     this.serverIndex = serverIndex;
     updateBasePath();
     return this;
   }
 
+  /**
+   * <p>Getter for the field <code>serverVariables</code>.</p>
+   *
+   * @return a {@link java.util.Map} of server variables.
+   */
   public Map<String, String> getServerVariables() {
     return serverVariables;
   }
 
+  /**
+   * <p>Setter for the field <code>serverVariables</code>.</p>
+   *
+   * @param serverVariables a {@link java.util.Map} of server variables.
+   * @return a {@link org.openapitools.client.ApiClient} object.
+   */
   public ApiClient setServerVariables(Map<String, String> serverVariables) {
     this.serverVariables = serverVariables;
     updateBasePath();
@@ -280,6 +328,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Helper method to set username for the first HTTP basic authentication.
    *
    * @param username Username
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setUsername(String username) {
     for (Authentication auth : authentications.values()) {
@@ -295,6 +344,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Helper method to set password for the first HTTP basic authentication.
    *
    * @param password Password
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setPassword(String password) {
     for (Authentication auth : authentications.values()) {
@@ -310,6 +360,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Helper method to set API key value for the first API key authentication.
    *
    * @param apiKey API key
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setApiKey(String apiKey) {
     for (Authentication auth : authentications.values()) {
@@ -325,6 +376,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Helper method to configure authentications which respects aliases of API keys.
    *
    * @param secrets Hash map from authentication name to its secret.
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient configureApiKeys(Map<String, String> secrets) {
     for (Map.Entry<String, Authentication> authEntry : authentications.entrySet()) {
@@ -345,6 +397,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Helper method to set API key prefix for the first API key authentication.
    *
    * @param apiKeyPrefix API key prefix
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setApiKeyPrefix(String apiKeyPrefix) {
     for (Authentication auth : authentications.values()) {
@@ -360,6 +413,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Helper method to set bearer token for the first Bearer authentication.
    *
    * @param bearerToken Bearer token
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setBearerToken(String bearerToken) {
     for (Authentication auth : authentications.values()) {
@@ -371,11 +425,11 @@ public class ApiClient extends JavaTimeFormatter {
     throw new RuntimeException("No Bearer authentication configured!");
   }
 
-
   /**
    * Set the User-Agent header's value (by adding to the default header map).
+   *
    * @param userAgent Http user agent
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setUserAgent(String userAgent) {
     this.userAgent = userAgent;
@@ -385,6 +439,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Get the User-Agent header's value.
+   *
    * @return User-Agent string
    */
   public String getUserAgent(){
@@ -396,7 +451,7 @@ public class ApiClient extends JavaTimeFormatter {
    *
    * @param key The header's key
    * @param value The header's value
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient addDefaultHeader(String key, String value) {
     defaultHeaderMap.put(key, value);
@@ -408,7 +463,7 @@ public class ApiClient extends JavaTimeFormatter {
    *
    * @param key The cookie's key
    * @param value The cookie's value
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient addDefaultCookie(String key, String value) {
     defaultCookieMap.put(key, value);
@@ -417,6 +472,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Gets the client config.
+   *
    * @return Client config
    */
   public ClientConfig getClientConfig() {
@@ -427,7 +483,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Set the client config.
    *
    * @param clientConfig Set the client config
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setClientConfig(ClientConfig clientConfig) {
     this.clientConfig = clientConfig;
@@ -438,6 +494,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Check that whether debugging is enabled for this API client.
+   *
    * @return True if debugging is switched on
    */
   public boolean isDebugging() {
@@ -448,7 +505,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Enable/disable debugging for this API client.
    *
    * @param debugging To enable (true) or disable (false) debugging
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setDebugging(boolean debugging) {
     this.debugging = debugging;
@@ -470,8 +527,9 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Set temp folder path
+   *
    * @param tempFolderPath Temp folder path
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setTempFolderPath(String tempFolderPath) {
     this.tempFolderPath = tempFolderPath;
@@ -480,6 +538,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Connect timeout (in milliseconds).
+   *
    * @return Connection timeout
    */
   public int getConnectTimeout() {
@@ -490,8 +549,9 @@ public class ApiClient extends JavaTimeFormatter {
    * Set the connect timeout (in milliseconds).
    * A value of 0 means no timeout, otherwise values must be between 1 and
    * {@link Integer#MAX_VALUE}.
+   *
    * @param connectionTimeout Connection timeout in milliseconds
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setConnectTimeout(int connectionTimeout) {
     this.connectionTimeout = connectionTimeout;
@@ -501,6 +561,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * read timeout (in milliseconds).
+   *
    * @return Read timeout
    */
   public int getReadTimeout() {
@@ -511,8 +572,9 @@ public class ApiClient extends JavaTimeFormatter {
    * Set the read timeout (in milliseconds).
    * A value of 0 means no timeout, otherwise values must be between 1 and
    * {@link Integer#MAX_VALUE}.
+   *
    * @param readTimeout Read timeout in milliseconds
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setReadTimeout(int readTimeout) {
     this.readTimeout = readTimeout;
@@ -522,6 +584,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Get the date format used to parse/format date parameters.
+   *
    * @return Date format
    */
   public DateFormat getDateFormat() {
@@ -530,8 +593,9 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Set the date format used to parse/format date parameters.
+   *
    * @param dateFormat Date format
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setDateFormat(DateFormat dateFormat) {
     this.dateFormat = dateFormat;
@@ -542,6 +606,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Parse the given string into Date object.
+   *
    * @param str String
    * @return Date
    */
@@ -555,6 +620,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Format the given Date object into string.
+   *
    * @param date Date
    * @return Date in string format
    */
@@ -564,6 +630,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Format the given parameter object into string.
+   *
    * @param param Object
    * @return Object in string format
    */
@@ -590,6 +657,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /*
    * Format to {@code Pair} objects.
+   *
    * @param collectionFormat Collection format
    * @param name Name
    * @param value Value
@@ -656,6 +724,7 @@ public class ApiClient extends JavaTimeFormatter {
    *   APPLICATION/JSON
    *   application/vnd.company+json
    * "* / *" is also default to JSON
+   *
    * @param mime MIME
    * @return True if the MIME type is JSON
    */
@@ -708,6 +777,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Escape the given string to be used as URL query value.
+   *
    * @param str String
    * @return Escaped string
    */
@@ -722,6 +792,7 @@ public class ApiClient extends JavaTimeFormatter {
   /**
    * Serialize the given Java object into string entity according the given
    * Content-Type (only JSON is supported for now).
+   *
    * @param obj Object
    * @param formParams Form parameters
    * @param contentType Context type
@@ -772,6 +843,7 @@ public class ApiClient extends JavaTimeFormatter {
   /**
    * Serialize the given Java object into string according the given
    * Content-Type (only JSON, HTTP form is supported for now).
+   *
    * @param obj Object
    * @param formParams Form parameters
    * @param contentType Context type
@@ -808,6 +880,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Deserialize response body to Java object according to the Content-Type.
+   *
    * @param <T> Type
    * @param response Response
    * @param returnType Return type
@@ -842,6 +915,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Download file from the given response.
+   *
    * @param response Response
    * @return File
    * @throws ApiException If fail to read file content from response and write to disk
@@ -856,6 +930,13 @@ public class ApiClient extends JavaTimeFormatter {
     }
   }
 
+  /**
+   * <p>Prepare the file for download from the response.</p>
+   *
+   * @param response a {@link javax.ws.rs.core.Response} object.
+   * @return a {@link java.io.File} object.
+   * @throws java.io.IOException if any.
+   */
   public File prepareDownloadFile(Response response) throws IOException {
     String filename = null;
     String contentDisposition = (String) response.getHeaders().getFirst("Content-Disposition");
@@ -1060,6 +1141,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Build the Client used to make HTTP requests.
+   *
    * @return Client
    */
   protected Client buildHttpClient() {
@@ -1074,6 +1156,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Get the default client config.
+   *
    * @return Client config
    */
   public ClientConfig getDefaultClientConfig() {
@@ -1110,6 +1193,8 @@ public class ApiClient extends JavaTimeFormatter {
    *
    * To completely disable certificate validation (at your own risk), you can
    * override this method and invoke disableCertificateValidation(clientBuilder).
+   *
+   * @param clientBuilder a {@link javax.ws.rs.client.ClientBuilder} object.
    */
   protected void customizeClientBuilder(ClientBuilder clientBuilder) {
     // No-op extension point
@@ -1120,6 +1205,10 @@ public class ApiClient extends JavaTimeFormatter {
    *
    * Please note that trusting all certificates is extremely risky.
    * This may be useful in a development environment with self-signed certificates.
+   *
+   * @param clientBuilder a {@link javax.ws.rs.client.ClientBuilder} object.
+   * @throws java.security.KeyManagementException if any.
+   * @throws java.security.NoSuchAlgorithmException if any.
    */
   protected void disableCertificateValidation(ClientBuilder clientBuilder) throws KeyManagementException, NoSuchAlgorithmException {
     TrustManager[] trustAllCerts = new X509TrustManager[] {
@@ -1141,6 +1230,12 @@ public class ApiClient extends JavaTimeFormatter {
     clientBuilder.sslContext(sslContext);
   }
 
+  /**
+   * <p>Build the response headers.</p>
+   *
+   * @param response a {@link javax.ws.rs.core.Response} object.
+   * @return a {@link java.util.Map} of response headers.
+   */
   protected Map<String, List<String>> buildResponseHeaders(Response response) {
     Map<String, List<String>> responseHeaders = new HashMap<String, List<String>>();
     for (Entry<String, List<Object>> entry: response.getHeaders().entrySet()) {
diff --git a/samples/openapi3/client/petstore/java/jersey2-java8-special-characters/src/main/java/org/openapitools/client/ApiClient.java b/samples/openapi3/client/petstore/java/jersey2-java8-special-characters/src/main/java/org/openapitools/client/ApiClient.java
index 727093b74f3..66eb9ca7f90 100644
--- a/samples/openapi3/client/petstore/java/jersey2-java8-special-characters/src/main/java/org/openapitools/client/ApiClient.java
+++ b/samples/openapi3/client/petstore/java/jersey2-java8-special-characters/src/main/java/org/openapitools/client/ApiClient.java
@@ -63,6 +63,9 @@ import org.openapitools.client.auth.HttpBasicAuth;
 import org.openapitools.client.auth.HttpBearerAuth;
 import org.openapitools.client.auth.ApiKeyAuth;
 
+/**
+ * <p>ApiClient class.</p>
+ */
 @javax.annotation.Generated(value = "org.openapitools.codegen.languages.JavaClientCodegen")
 public class ApiClient extends JavaTimeFormatter {
   protected Map<String, String> defaultHeaderMap = new HashMap<String, String>();
@@ -138,10 +141,21 @@ public class ApiClient extends JavaTimeFormatter {
     return json;
   }
 
+  /**
+   * <p>Getter for the field <code>httpClient</code>.</p>
+   *
+   * @return a {@link javax.ws.rs.client.Client} object.
+   */
   public Client getHttpClient() {
     return httpClient;
   }
 
+  /**
+   * <p>Setter for the field <code>httpClient</code>.</p>
+   *
+   * @param httpClient a {@link javax.ws.rs.client.Client} object.
+   * @return a {@link org.openapitools.client.ApiClient} object.
+   */
   public ApiClient setHttpClient(Client httpClient) {
     this.httpClient = httpClient;
     return this;
@@ -160,36 +174,70 @@ public class ApiClient extends JavaTimeFormatter {
    * Sets the base URL to the location where the OpenAPI document is being served.
    *
    * @param basePath The base URL to the target host.
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setBasePath(String basePath) {
     this.basePath = basePath;
     return this;
   }
 
+  /**
+   * <p>Getter for the field <code>servers</code>.</p>
+   *
+   * @return a {@link java.util.List} of servers.
+   */
   public List<ServerConfiguration> getServers() {
     return servers;
   }
 
+  /**
+   * <p>Setter for the field <code>servers</code>.</p>
+   *
+   * @param servers a {@link java.util.List} of servers.
+   * @return a {@link org.openapitools.client.ApiClient} object.
+   */
   public ApiClient setServers(List<ServerConfiguration> servers) {
     this.servers = servers;
     updateBasePath();
     return this;
   }
 
+  /**
+   * <p>Getter for the field <code>serverIndex</code>.</p>
+   *
+   * @return a {@link java.lang.Integer} object.
+   */
   public Integer getServerIndex() {
     return serverIndex;
   }
 
+  /**
+   * <p>Setter for the field <code>serverIndex</code>.</p>
+   *
+   * @param serverIndex the server index
+   * @return a {@link org.openapitools.client.ApiClient} object.
+   */
   public ApiClient setServerIndex(Integer serverIndex) {
     this.serverIndex = serverIndex;
     updateBasePath();
     return this;
   }
 
+  /**
+   * <p>Getter for the field <code>serverVariables</code>.</p>
+   *
+   * @return a {@link java.util.Map} of server variables.
+   */
   public Map<String, String> getServerVariables() {
     return serverVariables;
   }
 
+  /**
+   * <p>Setter for the field <code>serverVariables</code>.</p>
+   *
+   * @param serverVariables a {@link java.util.Map} of server variables.
+   * @return a {@link org.openapitools.client.ApiClient} object.
+   */
   public ApiClient setServerVariables(Map<String, String> serverVariables) {
     this.serverVariables = serverVariables;
     updateBasePath();
@@ -225,6 +273,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Helper method to set username for the first HTTP basic authentication.
    *
    * @param username Username
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setUsername(String username) {
     for (Authentication auth : authentications.values()) {
@@ -240,6 +289,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Helper method to set password for the first HTTP basic authentication.
    *
    * @param password Password
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setPassword(String password) {
     for (Authentication auth : authentications.values()) {
@@ -255,6 +305,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Helper method to set API key value for the first API key authentication.
    *
    * @param apiKey API key
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setApiKey(String apiKey) {
     for (Authentication auth : authentications.values()) {
@@ -270,6 +321,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Helper method to configure authentications which respects aliases of API keys.
    *
    * @param secrets Hash map from authentication name to its secret.
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient configureApiKeys(Map<String, String> secrets) {
     for (Map.Entry<String, Authentication> authEntry : authentications.entrySet()) {
@@ -290,6 +342,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Helper method to set API key prefix for the first API key authentication.
    *
    * @param apiKeyPrefix API key prefix
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setApiKeyPrefix(String apiKeyPrefix) {
     for (Authentication auth : authentications.values()) {
@@ -305,6 +358,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Helper method to set bearer token for the first Bearer authentication.
    *
    * @param bearerToken Bearer token
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setBearerToken(String bearerToken) {
     for (Authentication auth : authentications.values()) {
@@ -316,11 +370,11 @@ public class ApiClient extends JavaTimeFormatter {
     throw new RuntimeException("No Bearer authentication configured!");
   }
 
-
   /**
    * Set the User-Agent header's value (by adding to the default header map).
+   *
    * @param userAgent Http user agent
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setUserAgent(String userAgent) {
     this.userAgent = userAgent;
@@ -330,6 +384,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Get the User-Agent header's value.
+   *
    * @return User-Agent string
    */
   public String getUserAgent(){
@@ -341,7 +396,7 @@ public class ApiClient extends JavaTimeFormatter {
    *
    * @param key The header's key
    * @param value The header's value
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient addDefaultHeader(String key, String value) {
     defaultHeaderMap.put(key, value);
@@ -353,7 +408,7 @@ public class ApiClient extends JavaTimeFormatter {
    *
    * @param key The cookie's key
    * @param value The cookie's value
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient addDefaultCookie(String key, String value) {
     defaultCookieMap.put(key, value);
@@ -362,6 +417,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Gets the client config.
+   *
    * @return Client config
    */
   public ClientConfig getClientConfig() {
@@ -372,7 +428,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Set the client config.
    *
    * @param clientConfig Set the client config
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setClientConfig(ClientConfig clientConfig) {
     this.clientConfig = clientConfig;
@@ -383,6 +439,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Check that whether debugging is enabled for this API client.
+   *
    * @return True if debugging is switched on
    */
   public boolean isDebugging() {
@@ -393,7 +450,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Enable/disable debugging for this API client.
    *
    * @param debugging To enable (true) or disable (false) debugging
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setDebugging(boolean debugging) {
     this.debugging = debugging;
@@ -415,8 +472,9 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Set temp folder path
+   *
    * @param tempFolderPath Temp folder path
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setTempFolderPath(String tempFolderPath) {
     this.tempFolderPath = tempFolderPath;
@@ -425,6 +483,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Connect timeout (in milliseconds).
+   *
    * @return Connection timeout
    */
   public int getConnectTimeout() {
@@ -435,8 +494,9 @@ public class ApiClient extends JavaTimeFormatter {
    * Set the connect timeout (in milliseconds).
    * A value of 0 means no timeout, otherwise values must be between 1 and
    * {@link Integer#MAX_VALUE}.
+   *
    * @param connectionTimeout Connection timeout in milliseconds
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setConnectTimeout(int connectionTimeout) {
     this.connectionTimeout = connectionTimeout;
@@ -446,6 +506,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * read timeout (in milliseconds).
+   *
    * @return Read timeout
    */
   public int getReadTimeout() {
@@ -456,8 +517,9 @@ public class ApiClient extends JavaTimeFormatter {
    * Set the read timeout (in milliseconds).
    * A value of 0 means no timeout, otherwise values must be between 1 and
    * {@link Integer#MAX_VALUE}.
+   *
    * @param readTimeout Read timeout in milliseconds
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setReadTimeout(int readTimeout) {
     this.readTimeout = readTimeout;
@@ -467,6 +529,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Get the date format used to parse/format date parameters.
+   *
    * @return Date format
    */
   public DateFormat getDateFormat() {
@@ -475,8 +538,9 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Set the date format used to parse/format date parameters.
+   *
    * @param dateFormat Date format
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setDateFormat(DateFormat dateFormat) {
     this.dateFormat = dateFormat;
@@ -487,6 +551,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Parse the given string into Date object.
+   *
    * @param str String
    * @return Date
    */
@@ -500,6 +565,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Format the given Date object into string.
+   *
    * @param date Date
    * @return Date in string format
    */
@@ -509,6 +575,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Format the given parameter object into string.
+   *
    * @param param Object
    * @return Object in string format
    */
@@ -535,6 +602,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /*
    * Format to {@code Pair} objects.
+   *
    * @param collectionFormat Collection format
    * @param name Name
    * @param value Value
@@ -601,6 +669,7 @@ public class ApiClient extends JavaTimeFormatter {
    *   APPLICATION/JSON
    *   application/vnd.company+json
    * "* / *" is also default to JSON
+   *
    * @param mime MIME
    * @return True if the MIME type is JSON
    */
@@ -653,6 +722,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Escape the given string to be used as URL query value.
+   *
    * @param str String
    * @return Escaped string
    */
@@ -667,6 +737,7 @@ public class ApiClient extends JavaTimeFormatter {
   /**
    * Serialize the given Java object into string entity according the given
    * Content-Type (only JSON is supported for now).
+   *
    * @param obj Object
    * @param formParams Form parameters
    * @param contentType Context type
@@ -717,6 +788,7 @@ public class ApiClient extends JavaTimeFormatter {
   /**
    * Serialize the given Java object into string according the given
    * Content-Type (only JSON, HTTP form is supported for now).
+   *
    * @param obj Object
    * @param formParams Form parameters
    * @param contentType Context type
@@ -753,6 +825,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Deserialize response body to Java object according to the Content-Type.
+   *
    * @param <T> Type
    * @param response Response
    * @param returnType Return type
@@ -787,6 +860,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Download file from the given response.
+   *
    * @param response Response
    * @return File
    * @throws ApiException If fail to read file content from response and write to disk
@@ -801,6 +875,13 @@ public class ApiClient extends JavaTimeFormatter {
     }
   }
 
+  /**
+   * <p>Prepare the file for download from the response.</p>
+   *
+   * @param response a {@link javax.ws.rs.core.Response} object.
+   * @return a {@link java.io.File} object.
+   * @throws java.io.IOException if any.
+   */
   public File prepareDownloadFile(Response response) throws IOException {
     String filename = null;
     String contentDisposition = (String) response.getHeaders().getFirst("Content-Disposition");
@@ -1005,6 +1086,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Build the Client used to make HTTP requests.
+   *
    * @return Client
    */
   protected Client buildHttpClient() {
@@ -1019,6 +1101,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Get the default client config.
+   *
    * @return Client config
    */
   public ClientConfig getDefaultClientConfig() {
@@ -1055,6 +1138,8 @@ public class ApiClient extends JavaTimeFormatter {
    *
    * To completely disable certificate validation (at your own risk), you can
    * override this method and invoke disableCertificateValidation(clientBuilder).
+   *
+   * @param clientBuilder a {@link javax.ws.rs.client.ClientBuilder} object.
    */
   protected void customizeClientBuilder(ClientBuilder clientBuilder) {
     // No-op extension point
@@ -1065,6 +1150,10 @@ public class ApiClient extends JavaTimeFormatter {
    *
    * Please note that trusting all certificates is extremely risky.
    * This may be useful in a development environment with self-signed certificates.
+   *
+   * @param clientBuilder a {@link javax.ws.rs.client.ClientBuilder} object.
+   * @throws java.security.KeyManagementException if any.
+   * @throws java.security.NoSuchAlgorithmException if any.
    */
   protected void disableCertificateValidation(ClientBuilder clientBuilder) throws KeyManagementException, NoSuchAlgorithmException {
     TrustManager[] trustAllCerts = new X509TrustManager[] {
@@ -1086,6 +1175,12 @@ public class ApiClient extends JavaTimeFormatter {
     clientBuilder.sslContext(sslContext);
   }
 
+  /**
+   * <p>Build the response headers.</p>
+   *
+   * @param response a {@link javax.ws.rs.core.Response} object.
+   * @return a {@link java.util.Map} of response headers.
+   */
   protected Map<String, List<String>> buildResponseHeaders(Response response) {
     Map<String, List<String>> responseHeaders = new HashMap<String, List<String>>();
     for (Entry<String, List<Object>> entry: response.getHeaders().entrySet()) {
diff --git a/samples/openapi3/client/petstore/java/jersey2-java8/src/main/java/org/openapitools/client/ApiClient.java b/samples/openapi3/client/petstore/java/jersey2-java8/src/main/java/org/openapitools/client/ApiClient.java
index 2d889cc99d8..328fec6af92 100644
--- a/samples/openapi3/client/petstore/java/jersey2-java8/src/main/java/org/openapitools/client/ApiClient.java
+++ b/samples/openapi3/client/petstore/java/jersey2-java8/src/main/java/org/openapitools/client/ApiClient.java
@@ -66,6 +66,9 @@ import org.openapitools.client.auth.HttpSignatureAuth;
 import org.openapitools.client.auth.ApiKeyAuth;
 import org.openapitools.client.auth.OAuth;
 
+/**
+ * <p>ApiClient class.</p>
+ */
 @javax.annotation.Generated(value = "org.openapitools.codegen.languages.JavaClientCodegen")
 public class ApiClient extends JavaTimeFormatter {
   protected Map<String, String> defaultHeaderMap = new HashMap<String, String>();
@@ -256,10 +259,21 @@ public class ApiClient extends JavaTimeFormatter {
     return json;
   }
 
+  /**
+   * <p>Getter for the field <code>httpClient</code>.</p>
+   *
+   * @return a {@link javax.ws.rs.client.Client} object.
+   */
   public Client getHttpClient() {
     return httpClient;
   }
 
+  /**
+   * <p>Setter for the field <code>httpClient</code>.</p>
+   *
+   * @param httpClient a {@link javax.ws.rs.client.Client} object.
+   * @return a {@link org.openapitools.client.ApiClient} object.
+   */
   public ApiClient setHttpClient(Client httpClient) {
     this.httpClient = httpClient;
     return this;
@@ -278,6 +292,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Sets the base URL to the location where the OpenAPI document is being served.
    *
    * @param basePath The base URL to the target host.
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setBasePath(String basePath) {
     this.basePath = basePath;
@@ -285,30 +300,63 @@ public class ApiClient extends JavaTimeFormatter {
     return this;
   }
 
+  /**
+   * <p>Getter for the field <code>servers</code>.</p>
+   *
+   * @return a {@link java.util.List} of servers.
+   */
   public List<ServerConfiguration> getServers() {
     return servers;
   }
 
+  /**
+   * <p>Setter for the field <code>servers</code>.</p>
+   *
+   * @param servers a {@link java.util.List} of servers.
+   * @return a {@link org.openapitools.client.ApiClient} object.
+   */
   public ApiClient setServers(List<ServerConfiguration> servers) {
     this.servers = servers;
     updateBasePath();
     return this;
   }
 
+  /**
+   * <p>Getter for the field <code>serverIndex</code>.</p>
+   *
+   * @return a {@link java.lang.Integer} object.
+   */
   public Integer getServerIndex() {
     return serverIndex;
   }
 
+  /**
+   * <p>Setter for the field <code>serverIndex</code>.</p>
+   *
+   * @param serverIndex the server index
+   * @return a {@link org.openapitools.client.ApiClient} object.
+   */
   public ApiClient setServerIndex(Integer serverIndex) {
     this.serverIndex = serverIndex;
     updateBasePath();
     return this;
   }
 
+  /**
+   * <p>Getter for the field <code>serverVariables</code>.</p>
+   *
+   * @return a {@link java.util.Map} of server variables.
+   */
   public Map<String, String> getServerVariables() {
     return serverVariables;
   }
 
+  /**
+   * <p>Setter for the field <code>serverVariables</code>.</p>
+   *
+   * @param serverVariables a {@link java.util.Map} of server variables.
+   * @return a {@link org.openapitools.client.ApiClient} object.
+   */
   public ApiClient setServerVariables(Map<String, String> serverVariables) {
     this.serverVariables = serverVariables;
     updateBasePath();
@@ -352,6 +400,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Helper method to set username for the first HTTP basic authentication.
    *
    * @param username Username
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setUsername(String username) {
     for (Authentication auth : authentications.values()) {
@@ -367,6 +416,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Helper method to set password for the first HTTP basic authentication.
    *
    * @param password Password
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setPassword(String password) {
     for (Authentication auth : authentications.values()) {
@@ -382,6 +432,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Helper method to set API key value for the first API key authentication.
    *
    * @param apiKey API key
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setApiKey(String apiKey) {
     for (Authentication auth : authentications.values()) {
@@ -397,6 +448,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Helper method to configure authentications which respects aliases of API keys.
    *
    * @param secrets Hash map from authentication name to its secret.
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient configureApiKeys(Map<String, String> secrets) {
     for (Map.Entry<String, Authentication> authEntry : authentications.entrySet()) {
@@ -417,6 +469,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Helper method to set API key prefix for the first API key authentication.
    *
    * @param apiKeyPrefix API key prefix
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setApiKeyPrefix(String apiKeyPrefix) {
     for (Authentication auth : authentications.values()) {
@@ -432,6 +485,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Helper method to set bearer token for the first Bearer authentication.
    *
    * @param bearerToken Bearer token
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setBearerToken(String bearerToken) {
     for (Authentication auth : authentications.values()) {
@@ -443,10 +497,11 @@ public class ApiClient extends JavaTimeFormatter {
     throw new RuntimeException("No Bearer authentication configured!");
   }
 
-
   /**
    * Helper method to set access token for the first OAuth2 authentication.
+   *
    * @param accessToken Access token
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setAccessToken(String accessToken) {
     for (Authentication auth : authentications.values()) {
@@ -463,6 +518,7 @@ public class ApiClient extends JavaTimeFormatter {
    *
    * @param clientId the client ID
    * @param clientSecret the client secret
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setOauthCredentials(String clientId, String clientSecret) {
     for (Authentication auth : authentications.values()) {
@@ -479,6 +535,7 @@ public class ApiClient extends JavaTimeFormatter {
    *
    * @param username the user name
    * @param password the user password
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setOauthPasswordFlow(String username, String password) {
     for (Authentication auth : authentications.values()) {
@@ -494,6 +551,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Helper method to set the authorization code flow for the first OAuth2 authentication.
    *
    * @param code the authorization code
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setOauthAuthorizationCodeFlow(String code) {
     for (Authentication auth : authentications.values()) {
@@ -509,6 +567,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Helper method to set the scopes for the first OAuth2 authentication.
    *
    * @param scope the oauth scope
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setOauthScope(String scope) {
     for (Authentication auth : authentications.values()) {
@@ -522,8 +581,9 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Set the User-Agent header's value (by adding to the default header map).
+   *
    * @param userAgent Http user agent
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setUserAgent(String userAgent) {
     this.userAgent = userAgent;
@@ -533,6 +593,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Get the User-Agent header's value.
+   *
    * @return User-Agent string
    */
   public String getUserAgent(){
@@ -544,7 +605,7 @@ public class ApiClient extends JavaTimeFormatter {
    *
    * @param key The header's key
    * @param value The header's value
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient addDefaultHeader(String key, String value) {
     defaultHeaderMap.put(key, value);
@@ -556,7 +617,7 @@ public class ApiClient extends JavaTimeFormatter {
    *
    * @param key The cookie's key
    * @param value The cookie's value
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient addDefaultCookie(String key, String value) {
     defaultCookieMap.put(key, value);
@@ -565,6 +626,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Gets the client config.
+   *
    * @return Client config
    */
   public ClientConfig getClientConfig() {
@@ -575,7 +637,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Set the client config.
    *
    * @param clientConfig Set the client config
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setClientConfig(ClientConfig clientConfig) {
     this.clientConfig = clientConfig;
@@ -586,6 +648,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Check that whether debugging is enabled for this API client.
+   *
    * @return True if debugging is switched on
    */
   public boolean isDebugging() {
@@ -596,7 +659,7 @@ public class ApiClient extends JavaTimeFormatter {
    * Enable/disable debugging for this API client.
    *
    * @param debugging To enable (true) or disable (false) debugging
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setDebugging(boolean debugging) {
     this.debugging = debugging;
@@ -618,8 +681,9 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Set temp folder path
+   *
    * @param tempFolderPath Temp folder path
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setTempFolderPath(String tempFolderPath) {
     this.tempFolderPath = tempFolderPath;
@@ -628,6 +692,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Connect timeout (in milliseconds).
+   *
    * @return Connection timeout
    */
   public int getConnectTimeout() {
@@ -638,8 +703,9 @@ public class ApiClient extends JavaTimeFormatter {
    * Set the connect timeout (in milliseconds).
    * A value of 0 means no timeout, otherwise values must be between 1 and
    * {@link Integer#MAX_VALUE}.
+   *
    * @param connectionTimeout Connection timeout in milliseconds
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setConnectTimeout(int connectionTimeout) {
     this.connectionTimeout = connectionTimeout;
@@ -649,6 +715,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * read timeout (in milliseconds).
+   *
    * @return Read timeout
    */
   public int getReadTimeout() {
@@ -659,8 +726,9 @@ public class ApiClient extends JavaTimeFormatter {
    * Set the read timeout (in milliseconds).
    * A value of 0 means no timeout, otherwise values must be between 1 and
    * {@link Integer#MAX_VALUE}.
+   *
    * @param readTimeout Read timeout in milliseconds
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setReadTimeout(int readTimeout) {
     this.readTimeout = readTimeout;
@@ -670,6 +738,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Get the date format used to parse/format date parameters.
+   *
    * @return Date format
    */
   public DateFormat getDateFormat() {
@@ -678,8 +747,9 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Set the date format used to parse/format date parameters.
+   *
    * @param dateFormat Date format
-   * @return API client
+   * @return a {@link org.openapitools.client.ApiClient} object.
    */
   public ApiClient setDateFormat(DateFormat dateFormat) {
     this.dateFormat = dateFormat;
@@ -690,6 +760,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Parse the given string into Date object.
+   *
    * @param str String
    * @return Date
    */
@@ -703,6 +774,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Format the given Date object into string.
+   *
    * @param date Date
    * @return Date in string format
    */
@@ -712,6 +784,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Format the given parameter object into string.
+   *
    * @param param Object
    * @return Object in string format
    */
@@ -738,6 +811,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /*
    * Format to {@code Pair} objects.
+   *
    * @param collectionFormat Collection format
    * @param name Name
    * @param value Value
@@ -804,6 +878,7 @@ public class ApiClient extends JavaTimeFormatter {
    *   APPLICATION/JSON
    *   application/vnd.company+json
    * "* / *" is also default to JSON
+   *
    * @param mime MIME
    * @return True if the MIME type is JSON
    */
@@ -856,6 +931,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Escape the given string to be used as URL query value.
+   *
    * @param str String
    * @return Escaped string
    */
@@ -870,6 +946,7 @@ public class ApiClient extends JavaTimeFormatter {
   /**
    * Serialize the given Java object into string entity according the given
    * Content-Type (only JSON is supported for now).
+   *
    * @param obj Object
    * @param formParams Form parameters
    * @param contentType Context type
@@ -920,6 +997,7 @@ public class ApiClient extends JavaTimeFormatter {
   /**
    * Serialize the given Java object into string according the given
    * Content-Type (only JSON, HTTP form is supported for now).
+   *
    * @param obj Object
    * @param formParams Form parameters
    * @param contentType Context type
@@ -956,6 +1034,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Deserialize response body to Java object according to the Content-Type.
+   *
    * @param <T> Type
    * @param response Response
    * @param returnType Return type
@@ -990,6 +1069,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Download file from the given response.
+   *
    * @param response Response
    * @return File
    * @throws ApiException If fail to read file content from response and write to disk
@@ -1004,6 +1084,13 @@ public class ApiClient extends JavaTimeFormatter {
     }
   }
 
+  /**
+   * <p>Prepare the file for download from the response.</p>
+   *
+   * @param response a {@link javax.ws.rs.core.Response} object.
+   * @return a {@link java.io.File} object.
+   * @throws java.io.IOException if any.
+   */
   public File prepareDownloadFile(Response response) throws IOException {
     String filename = null;
     String contentDisposition = (String) response.getHeaders().getFirst("Content-Disposition");
@@ -1224,6 +1311,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Build the Client used to make HTTP requests.
+   *
    * @return Client
    */
   protected Client buildHttpClient() {
@@ -1238,6 +1326,7 @@ public class ApiClient extends JavaTimeFormatter {
 
   /**
    * Get the default client config.
+   *
    * @return Client config
    */
   public ClientConfig getDefaultClientConfig() {
@@ -1274,6 +1363,8 @@ public class ApiClient extends JavaTimeFormatter {
    *
    * To completely disable certificate validation (at your own risk), you can
    * override this method and invoke disableCertificateValidation(clientBuilder).
+   *
+   * @param clientBuilder a {@link javax.ws.rs.client.ClientBuilder} object.
    */
   protected void customizeClientBuilder(ClientBuilder clientBuilder) {
     // No-op extension point
@@ -1284,6 +1375,10 @@ public class ApiClient extends JavaTimeFormatter {
    *
    * Please note that trusting all certificates is extremely risky.
    * This may be useful in a development environment with self-signed certificates.
+   *
+   * @param clientBuilder a {@link javax.ws.rs.client.ClientBuilder} object.
+   * @throws java.security.KeyManagementException if any.
+   * @throws java.security.NoSuchAlgorithmException if any.
    */
   protected void disableCertificateValidation(ClientBuilder clientBuilder) throws KeyManagementException, NoSuchAlgorithmException {
     TrustManager[] trustAllCerts = new X509TrustManager[] {
@@ -1305,6 +1400,12 @@ public class ApiClient extends JavaTimeFormatter {
     clientBuilder.sslContext(sslContext);
   }
 
+  /**
+   * <p>Build the response headers.</p>
+   *
+   * @param response a {@link javax.ws.rs.core.Response} object.
+   * @return a {@link java.util.Map} of response headers.
+   */
   protected Map<String, List<String>> buildResponseHeaders(Response response) {
     Map<String, List<String>> responseHeaders = new HashMap<String, List<String>>();
     for (Entry<String, List<Object>> entry: response.getHeaders().entrySet()) {