better comment/docstrings in jersey2 apiclient (#10668)

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()) {