better comment/docstrings in jersey2 apiclient (#10668)

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