loafle/openapi-generator
3
0
Fork 0
forked from loafle/openapi-generator-original
Code Pull Requests Activity

[Java][okhttp] better docstring (#10741)

Browse Source 
* better docstring in api client, exception, response

* more docstring update
This commit is contained in:
William Cheng
2021-11-01 00:47:32 +08:00
committed by GitHub
parent 68b5f866ff
commit 9546a5a61b
15 changed files with 742 additions and 106 deletions
Download Patch File Download Diff File Expand all files Collapse all files

83
samples/client/petstore/java/okhttp-gson-dynamicOperations/src/main/java/org/openapitools/client/ApiClient.java
View File

@@ -65,6 +65,9 @@ import org.openapitools.client.auth.OAuth;
import org.openapitools.client.auth.RetryingOAuth;
import org.openapitools.client.auth.OAuthFlow;
/**
* <p>ApiClient class.</p>
*/
public class ApiClient {
private String basePath = "http://petstore.swagger.io:80/v2";
@@ -91,7 +94,7 @@ public class ApiClient {
private Map<String, ApiOperation> operationLookupMap = new HashMap<>();
/*
/**
* Basic constructor for ApiClient
*/
public ApiClient() {
@@ -107,8 +110,10 @@ public class ApiClient {
authentications = Collections.unmodifiableMap(authentications);
}
/*
/**
* Basic constructor with custom OkHttpClient
*
* @param client a {@link okhttp3.OkHttpClient} object
*/
public ApiClient(OkHttpClient client) {
init();
@@ -124,28 +129,28 @@ public class ApiClient {
authentications = Collections.unmodifiableMap(authentications);
}
/*
/**
* Constructor for ApiClient to support access token retry on 401/403 configured with client ID
*/
public ApiClient(String clientId) {
this(clientId, null, null);
}
/*
/**
* Constructor for ApiClient to support access token retry on 401/403 configured with client ID and additional parameters
*/
public ApiClient(String clientId, Map<String, String> parameters) {
this(clientId, null, parameters);
}
/*
/**
* Constructor for ApiClient to support access token retry on 401/403 configured with client ID, secret, and additional parameters
*/
public ApiClient(String clientId, String clientSecret, Map<String, String> parameters) {
this(null, clientId, clientSecret, parameters);
}
/*
/**
* Constructor for ApiClient to support access token retry on 401/403 configured with base path, client ID, secret, and additional parameters
*/
public ApiClient(String basePath, String clientId, String clientSecret, Map<String, String> parameters) {
@@ -241,7 +246,7 @@ public class ApiClient {
*
* @param newHttpClient An instance of OkHttpClient
* @return Api Client
* @throws NullPointerException when newHttpClient is null
* @throws java.lang.NullPointerException when newHttpClient is null
*/
public ApiClient setHttpClient(OkHttpClient newHttpClient) {
this.httpClient = Objects.requireNonNull(newHttpClient, "HttpClient must not be null!");
@@ -313,6 +318,11 @@ public class ApiClient {
return this;
}
/**
* <p>Getter for the field <code>keyManagers</code>.</p>
*
* @return an array of {@link javax.net.ssl.KeyManager} objects
*/
public KeyManager[] getKeyManagers() {
return keyManagers;
}
@@ -330,30 +340,65 @@ public class ApiClient {
return this;
}
/**
* <p>Getter for the field <code>dateFormat</code>.</p>
*
* @return a {@link java.text.DateFormat} object
*/
public DateFormat getDateFormat() {
return dateFormat;
}
/**
* <p>Setter for the field <code>dateFormat</code>.</p>
*
* @param dateFormat a {@link java.text.DateFormat} object
* @return a {@link org.openapitools.client.ApiClient} object
*/
public ApiClient setDateFormat(DateFormat dateFormat) {
this.json.setDateFormat(dateFormat);
return this;
}
/**
* <p>Set SqlDateFormat.</p>
*
* @param dateFormat a {@link java.text.DateFormat} object
* @return a {@link org.openapitools.client.ApiClient} object
*/
public ApiClient setSqlDateFormat(DateFormat dateFormat) {
this.json.setSqlDateFormat(dateFormat);
return this;
}
/**
* <p>Set OffsetDateTimeFormat.</p>
*
* @param dateFormat a {@link org.threeten.bp.format.DateTimeFormatter} object
* @return a {@link org.openapitools.client.ApiClient} object
*/
public ApiClient setOffsetDateTimeFormat(DateTimeFormatter dateFormat) {
this.json.setOffsetDateTimeFormat(dateFormat);
return this;
}
/**
* <p>Set LocalDateFormat.</p>
*
* @param dateFormat a {@link org.threeten.bp.format.DateTimeFormatter} object
* @return a {@link org.openapitools.client.ApiClient} object
*/
public ApiClient setLocalDateFormat(DateTimeFormatter dateFormat) {
this.json.setLocalDateFormat(dateFormat);
return this;
}
/**
* <p>Set LenientOnJson.</p>
*
* @param lenientOnJson a boolean
* @return a {@link org.openapitools.client.ApiClient} object
*/
public ApiClient setLenientOnJson(boolean lenientOnJson) {
this.json.setLenientOnJson(lenientOnJson);
return this;
@@ -556,7 +601,7 @@ public class ApiClient {
/**
* Sets the connect timeout (in milliseconds).
* A value of 0 means no timeout, otherwise values must be between 1 and
* {@link Integer#MAX_VALUE}.
* {@link java.lang.Integer#MAX_VALUE}.
*
* @param connectionTimeout connection timeout in milliseconds
* @return Api client
@@ -578,7 +623,7 @@ public class ApiClient {
/**
* Sets the read timeout (in milliseconds).
* A value of 0 means no timeout, otherwise values must be between 1 and
* {@link Integer#MAX_VALUE}.
* {@link java.lang.Integer#MAX_VALUE}.
*
* @param readTimeout read timeout in milliseconds
* @return Api client
@@ -600,7 +645,7 @@ public class ApiClient {
/**
* Sets the write timeout (in milliseconds).
* A value of 0 means no timeout, otherwise values must be between 1 and
* {@link Integer#MAX_VALUE}.
* {@link java.lang.Integer#MAX_VALUE}.
*
* @param writeTimeout connection timeout in milliseconds
* @return Api client
@@ -836,7 +881,7 @@ public class ApiClient {
* @param response HTTP response
* @param returnType The type of the Java object
* @return The deserialized Java object
* @throws ApiException If fail to deserialize response body, i.e. cannot read response body
* @throws org.openapitools.client.ApiException If fail to deserialize response body, i.e. cannot read response body
* or the Content-Type of the response is not supported.
*/
@SuppressWarnings("unchecked")
@@ -897,7 +942,7 @@ public class ApiClient {
* @param obj The Java object
* @param contentType The request Content-Type
* @return The serialized request body
* @throws ApiException If fail to serialize the given object
* @throws org.openapitools.client.ApiException If fail to serialize the given object
*/
public RequestBody serialize(Object obj, String contentType) throws ApiException {
if (obj instanceof byte[]) {
@@ -923,7 +968,7 @@ public class ApiClient {
* Download file from the given response.
*
* @param response An instance of the Response object
* @throws ApiException If fail to read file content from response and write to disk
* @throws org.openapitools.client.ApiException If fail to read file content from response and write to disk
* @return Downloaded file
*/
public File downloadFileFromResponse(Response response) throws ApiException {
@@ -943,7 +988,7 @@ public class ApiClient {
*
* @param response An instance of the Response object
* @return Prepared file for the download
* @throws IOException If fail to prepare file for download
* @throws java.io.IOException If fail to prepare file for download
*/
public File prepareDownloadFile(Response response) throws IOException {
String filename = null;
@@ -987,7 +1032,7 @@ public class ApiClient {
* @param <T> Type
* @param call An instance of the Call object
* @return ApiResponse&lt;T&gt;
* @throws ApiException If fail to execute the call
* @throws org.openapitools.client.ApiException If fail to execute the call
*/
public <T> ApiResponse<T> execute(Call call) throws ApiException {
return execute(call, null);
@@ -1002,7 +1047,7 @@ public class ApiClient {
* @return ApiResponse object containing response status, headers and
* data, which is a Java object deserialized from response body and would be null
* when returnType is null.
* @throws ApiException If fail to execute the call
* @throws org.openapitools.client.ApiException If fail to execute the call
*/
public <T> ApiResponse<T> execute(Call call, Type returnType) throws ApiException {
try {
@@ -1066,7 +1111,7 @@ public class ApiClient {
* @param response Response
* @param returnType Return type
* @return Type
* @throws ApiException If the response has an unsuccessful status code or
* @throws org.openapitools.client.ApiException If the response has an unsuccessful status code or
* fail to deserialize the response body
*/
public <T> T handleResponse(Response response, Type returnType) throws ApiException {
@@ -1112,7 +1157,7 @@ public class ApiClient {
* @param authNames The authentications to apply
* @param callback Callback for upload/download progress
* @return The HTTP call
* @throws ApiException If fail to serialize the request body object
* @throws org.openapitools.client.ApiException If fail to serialize the request body object
*/
public Call buildCall(String path, String method, List<Pair> queryParams, List<Pair> collectionQueryParams, Object body, Map<String, String> headerParams, Map<String, String> cookieParams, Map<String, Object> formParams, String[] authNames, ApiCallback callback) throws ApiException {
Request request = buildRequest(path, method, queryParams, collectionQueryParams, body, headerParams, cookieParams, formParams, authNames, callback);
@@ -1134,7 +1179,7 @@ public class ApiClient {
* @param authNames The authentications to apply
* @param callback Callback for upload/download progress
* @return The HTTP request
* @throws ApiException If fail to serialize the request body object
* @throws org.openapitools.client.ApiException If fail to serialize the request body object
*/
public Request buildRequest(String path, String method, List<Pair> queryParams, List<Pair> collectionQueryParams, Object body, Map<String, String> headerParams, Map<String, String> cookieParams, Map<String, Object> formParams, String[] authNames, ApiCallback callback) throws ApiException {
updateParamsForAuth(authNames, queryParams, headerParams, cookieParams);

64
samples/client/petstore/java/okhttp-gson-dynamicOperations/src/main/java/org/openapitools/client/ApiException.java
View File

@@ -16,22 +16,47 @@ package org.openapitools.client;
import java.util.Map;
import java.util.List;
/**
* <p>ApiException class.</p>
*/
@javax.annotation.Generated(value = "org.openapitools.codegen.languages.JavaClientCodegen")
public class ApiException extends Exception {
private int code = 0;
private Map<String, List<String>> responseHeaders = null;
private String responseBody = null;
/**
* <p>Constructor for ApiException.</p>
*/
public ApiException() {}
/**
* <p>Constructor for ApiException.</p>
*
* @param throwable a {@link java.lang.Throwable} object
*/
public ApiException(Throwable throwable) {
super(throwable);
}
/**
* <p>Constructor for ApiException.</p>
*
* @param message the error message
*/
public ApiException(String message) {
super(message);
}
/**
* <p>Constructor for ApiException.</p>
*
* @param message the error message
* @param throwable a {@link java.lang.Throwable} object
* @param code HTTP status code
* @param responseHeaders a {@link java.util.Map} of HTTP response headers
* @param responseBody the response body
*/
public ApiException(String message, Throwable throwable, int code, Map<String, List<String>> responseHeaders, String responseBody) {
super(message, throwable);
this.code = code;
@@ -39,23 +64,60 @@ public class ApiException extends Exception {
this.responseBody = responseBody;
}
/**
* <p>Constructor for ApiException.</p>
*
* @param message the error message
* @param code HTTP status code
* @param responseHeaders a {@link java.util.Map} of HTTP response headers
* @param responseBody the response body
*/
public ApiException(String message, int code, Map<String, List<String>> responseHeaders, String responseBody) {
this(message, (Throwable) null, code, responseHeaders, responseBody);
}
/**
* <p>Constructor for ApiException.</p>
*
* @param message the error message
* @param throwable a {@link java.lang.Throwable} object
* @param code HTTP status code
* @param responseHeaders a {@link java.util.Map} of HTTP response headers
*/
public ApiException(String message, Throwable throwable, int code, Map<String, List<String>> responseHeaders) {
this(message, throwable, code, responseHeaders, null);
}
/**
* <p>Constructor for ApiException.</p>
*
* @param code HTTP status code
* @param responseHeaders a {@link java.util.Map} of HTTP response headers
* @param responseBody the response body
*/
public ApiException(int code, Map<String, List<String>> responseHeaders, String responseBody) {
this((String) null, (Throwable) null, code, responseHeaders, responseBody);
}
/**
* <p>Constructor for ApiException.</p>
*
* @param code HTTP status code
* @param message a {@link java.lang.String} object
*/
public ApiException(int code, String message) {
super(message);
this.code = code;
}
/**
* <p>Constructor for ApiException.</p>
*
* @param code HTTP status code
* @param message the error message
* @param responseHeaders a {@link java.util.Map} of HTTP response headers
* @param responseBody the response body
*/
public ApiException(int code, String message, Map<String, List<String>> responseHeaders, String responseBody) {
this(code, message);
this.responseHeaders = responseHeaders;

21
samples/client/petstore/java/okhttp-gson-dynamicOperations/src/main/java/org/openapitools/client/ApiResponse.java
View File

@@ -18,8 +18,6 @@ import java.util.Map;
/**
* API response returned by API call.
*
* @param <T> The type of data that is deserialized from response body
*/
public class ApiResponse<T> {
final private int statusCode;
@@ -27,6 +25,8 @@ public class ApiResponse<T> {
final private T data;
/**
* <p>Constructor for ApiResponse.</p>
*
* @param statusCode The status code of HTTP response
* @param headers The headers of HTTP response
*/
@@ -35,6 +35,8 @@ public class ApiResponse<T> {
}
/**
* <p>Constructor for ApiResponse.</p>
*
* @param statusCode The status code of HTTP response
* @param headers The headers of HTTP response
* @param data The object deserialized from response bod
@@ -45,14 +47,29 @@ public class ApiResponse<T> {
this.data = data;
}
/**
* <p>Get the <code>status code</code>.</p>
*
* @return the status code
*/
public int getStatusCode() {
return statusCode;
}
/**
* <p>Get the <code>headers</code>.</p>
*
* @return a {@link java.util.Map} of headers
*/
public Map<String, List<String>> getHeaders() {
return headers;
}
/**
* <p>Get the <code>data</code>.</p>
*
* @return the data
*/
public T getData() {
return data;
}