JavaDoc fixes for Java/RESTEasy client (#151)

modules/openapi-generator/src/main/resources/Java/libraries/resteasy/ApiClient.mustache

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

modules/openapi-generator/src/main/resources/Java/libraries/resteasy/JSON.mustache

@@ -36,6 +36,7 @@ public class JSON implements ContextResolver<ObjectMapper> {
 
   /**
    * Set the date format for JSON (de)serialization with Date properties.
+   * @param dateFormat the date format to set
    */
   public void setDateFormat(DateFormat dateFormat) {
     mapper.setDateFormat(dateFormat);

modules/openapi-generator/src/main/resources/Java/libraries/resteasy/api.mustache

@@ -43,7 +43,7 @@ public class {{classname}} {
    * {{summary}}
    * {{notes}}{{#allParams}}
    * @param {{paramName}} {{description}}{{#required}} (required){{/required}}{{^required}} (optional{{#defaultValue}}, default to {{.}}{{/defaultValue}}){{/required}}{{/allParams}}{{#returnType}}
-   * @return {{{returnType}}}{{/returnType}}
+   * @return a {@code {{{returnType}}}}{{/returnType}}
    * @throws ApiException if fails to make API call
    {{#isDeprecated}}
    * @deprecated

modules/openapi-generator/src/main/resources/Java/libraries/resteasy/pom.mustache

@@ -134,6 +134,14 @@
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-javadoc-plugin</artifactId>
                 <version>2.10.4</version>
+                <executions>
+                    <execution>
+                        <id>attach-javadocs</id>
+                        <goals>
+                            <goal>jar</goal>
+                        </goals>
+                    </execution>
+                </executions>
             </plugin>
         </plugins>
     </build>

samples/client/petstore/java/resteasy/pom.xml

@@ -128,6 +128,14 @@
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-javadoc-plugin</artifactId>
                 <version>2.10.4</version>
+                <executions>
+                    <execution>
+                        <id>attach-javadocs</id>
+                        <goals>
+                            <goal>jar</goal>
+                        </goals>
+                    </execution>
+                </executions>
             </plugin>
         </plugins>
     </build>

samples/client/petstore/java/resteasy/src/main/java/org/openapitools/client/ApiClient.java

@@ -86,6 +86,7 @@ public class ApiClient {
 
   /**
    * Gets the JSON instance to do JSON serialization and deserialization.
+   * @return the JSON utility class
    */
   public JSON getJSON() {
     return json;
@@ -111,6 +112,7 @@ public class ApiClient {
 
   /**
    * Gets the status code of the previous request
+   * @return the status code of the previous request
    */
   public int getStatusCode() {
     return statusCode;
@@ -118,6 +120,7 @@ public class ApiClient {
 
   /**
    * Gets the response headers of the previous request
+   * @return the response headers of the previous request
    */
   public Map<String, List<String>> getResponseHeaders() {
     return responseHeaders;
@@ -125,6 +128,7 @@ public class ApiClient {
 
   /**
    * Get authentications (key: authentication name, value: authentication).
+   * @return the authentications
    */
   public Map<String, Authentication> getAuthentications() {
     return authentications;
@@ -142,6 +146,7 @@ public class ApiClient {
 
   /**
    * Helper method to set username for the first HTTP basic authentication.
+   * @param username the username
    */
   public void setUsername(String username) {
     for (Authentication auth : authentications.values()) {
@@ -155,6 +160,7 @@ public class ApiClient {
 
   /**
    * Helper method to set password for the first HTTP basic authentication.
+   * @param password the password
    */
   public void setPassword(String password) {
     for (Authentication auth : authentications.values()) {
@@ -168,6 +174,7 @@ public class ApiClient {
 
   /**
    * Helper method to set API key value for the first API key authentication.
+   * @param apiKey the API key
    */
   public void setApiKey(String apiKey) {
     for (Authentication auth : authentications.values()) {
@@ -181,6 +188,7 @@ public class ApiClient {
 
   /**
    * Helper method to set API key prefix for the first API key authentication.
+   * @param apiKeyPrefix the API key prefix
    */
   public void setApiKeyPrefix(String apiKeyPrefix) {
     for (Authentication auth : authentications.values()) {
@@ -194,6 +202,7 @@ public class ApiClient {
 
   /**
    * Helper method to set access token for the first OAuth2 authentication.
+   * @param accessToken the access token
    */
   public void setAccessToken(String accessToken) {
     for (Authentication auth : authentications.values()) {
@@ -207,6 +216,8 @@ public class ApiClient {
 
   /**
    * Set the User-Agent header's value (by adding to the default header map).
+   * @param userAgent the User-Agent header value
+   * @return this {@code ApiClient}
    */
   public ApiClient setUserAgent(String userAgent) {
     addDefaultHeader("User-Agent", userAgent);
@@ -218,6 +229,7 @@ public class ApiClient {
    *
    * @param key The header's key
    * @param value The header's value
+   * @return this {@code ApiClient}
    */
   public ApiClient addDefaultHeader(String key, String value) {
     defaultHeaderMap.put(key, value);
@@ -226,6 +238,7 @@ public class ApiClient {
 
   /**
    * Check that whether debugging is enabled for this API client.
+   * @return {@code true} if debugging is enabled for this API client
    */
   public boolean isDebugging() {
     return debugging;
@@ -235,6 +248,7 @@ public class ApiClient {
    * Enable/disable debugging for this API client.
    *
    * @param debugging To enable (true) or disable (false) debugging
+   * @return this {@code ApiClient}
    */
   public ApiClient setDebugging(boolean debugging) {
     this.debugging = debugging;
@@ -248,7 +262,8 @@ public class ApiClient {
    * with file response. The default value is <code>null</code>, i.e. using
    * the system's default tempopary folder.
    *
-   * @see https://docs.oracle.com/javase/7/docs/api/java/io/File.html#createTempFile(java.lang.String,%20java.lang.String,%20java.io.File)
+   * @return the temporary folder path
+   * @see <a href="https://docs.oracle.com/javase/7/docs/api/java/io/File.html#createTempFile(java.lang.String,%20java.lang.String,%20java.io.File)"></a>
    */
   public String getTempFolderPath() {
     return tempFolderPath;
@@ -261,6 +276,7 @@ public class ApiClient {
 
   /**
    * Get the date format used to parse/format date parameters.
+   * @return the date format used to parse/format date parameters
    */
   public DateFormat getDateFormat() {
     return dateFormat;
@@ -268,6 +284,8 @@ public class ApiClient {
 
   /**
    * Set the date format used to parse/format date parameters.
+   * @param dateFormat a date format used to parse/format date parameters
+   * @return this {@code ApiClient}
    */
   public ApiClient setDateFormat(DateFormat dateFormat) {
     this.dateFormat = dateFormat;
@@ -278,6 +296,8 @@ public class ApiClient {
 
   /**
    * Parse the given string into Date object.
+   * @param str a string to parse
+   * @return a {@code Date} object
    */
   public Date parseDate(String str) {
     try {
@@ -289,6 +309,8 @@ public class ApiClient {
 
   /**
    * Format the given Date object into string.
+   * @param date a {@code Date} object to format
+   * @return the {@code String} version of the {@code Date} object
    */
   public String formatDate(Date date) {
     return dateFormat.format(date);
@@ -296,6 +318,8 @@ public class ApiClient {
 
   /**
    * Format the given parameter object into string.
+   * @param param an object to format
+   * @return the {@code String} version of the object
    */
   public String parameterToString(Object param) {
     if (param == null) {
@@ -431,6 +455,8 @@ public class ApiClient {
 
   /**
    * Escape the given string to be used as URL query value.
+   * @param str a {@code String} to escape
+   * @return the escaped version of the {@code String}
    */
   public String escapeString(String str) {
     try {
@@ -443,6 +469,11 @@ public class ApiClient {
   /**
    * Serialize the given Java object into string entity according the given
    * Content-Type (only JSON is supported for now).
+   * @param obj the object to serialize
+   * @param formParams the form parameters
+   * @param contentType the content type
+   * @return an {@code Entity}
+   * @throws ApiException on failure to serialize
    */
   public Entity<?> serialize(Object obj, Map<String, Object> formParams, String contentType) throws ApiException {
     Entity<?> entity = null;
@@ -477,6 +508,11 @@ public class ApiClient {
 
   /**
    * Deserialize response body to Java object according to the Content-Type.
+   * @param <T> a Java type parameter
+   * @param response the response body to deserialize
+   * @param returnType a Java type to deserialize into
+   * @return a deserialized Java object
+   * @throws ApiException on failure to deserialize
    */
   public <T> T deserialize(Response response, GenericType<T> returnType) throws ApiException {
     if (response == null || returnType == null) {
@@ -505,6 +541,8 @@ public class ApiClient {
 
   /**
    * Download file from the given response.
+   * @param response a response
+   * @return a file from the given response
    * @throws ApiException If fail to read file content from response and write to disk
    */
   public File downloadFileFromResponse(Response response) throws ApiException {
@@ -555,6 +593,7 @@ public class ApiClient {
   /**
    * Invoke API by sending HTTP request with the given options.
    *
+   * @param <T> a Java type parameter
    * @param path The sub-path of the HTTP URL
    * @param method The request method, one of "GET", "POST", "PUT", "HEAD" and "DELETE"
    * @param queryParams The query parameters
@@ -566,6 +605,7 @@ public class ApiClient {
    * @param authNames The authentications to apply
    * @param returnType The return type into which to deserialize the response
    * @return The response body in type of string
+   * @throws ApiException if the invocation failed
    */
   public <T> T invokeAPI(String path, String method, List<Pair> queryParams, Object body, Map<String, String> headerParams, Map<String, Object> formParams, String accept, String contentType, String[] authNames, GenericType<T> returnType) throws ApiException {
     updateParamsForAuth(authNames, queryParams, headerParams);

samples/client/petstore/java/resteasy/src/main/java/org/openapitools/client/JSON.java

@@ -26,6 +26,7 @@ public class JSON implements ContextResolver<ObjectMapper> {
 
   /**
    * Set the date format for JSON (de)serialization with Date properties.
+   * @param dateFormat the date format to set
    */
   public void setDateFormat(DateFormat dateFormat) {
     mapper.setDateFormat(dateFormat);

samples/client/petstore/java/resteasy/src/main/java/org/openapitools/client/api/AnotherFakeApi.java

@@ -38,7 +38,7 @@ public class AnotherFakeApi {
    * To test special tags
    * To test special tags
    * @param client client model (required)
-   * @return Client
+   * @return a {@code Client}
    * @throws ApiException if fails to make API call
    */
   public Client testSpecialTags(Client client) throws ApiException {

samples/client/petstore/java/resteasy/src/main/java/org/openapitools/client/api/FakeApi.java

@@ -44,7 +44,7 @@ public class FakeApi {
    * 
    * Test serialization of outer boolean types
    * @param body Input boolean as post body (optional)
-   * @return Boolean
+   * @return a {@code Boolean}
    * @throws ApiException if fails to make API call
    */
   public Boolean fakeOuterBooleanSerialize(Boolean body) throws ApiException {
@@ -80,7 +80,7 @@ public class FakeApi {
    * 
    * Test serialization of object with outer number type
    * @param outerComposite Input composite as post body (optional)
-   * @return OuterComposite
+   * @return a {@code OuterComposite}
    * @throws ApiException if fails to make API call
    */
   public OuterComposite fakeOuterCompositeSerialize(OuterComposite outerComposite) throws ApiException {
@@ -116,7 +116,7 @@ public class FakeApi {
    * 
    * Test serialization of outer number types
    * @param body Input number as post body (optional)
-   * @return BigDecimal
+   * @return a {@code BigDecimal}
    * @throws ApiException if fails to make API call
    */
   public BigDecimal fakeOuterNumberSerialize(BigDecimal body) throws ApiException {
@@ -152,7 +152,7 @@ public class FakeApi {
    * 
    * Test serialization of outer string types
    * @param body Input string as post body (optional)
-   * @return String
+   * @return a {@code String}
    * @throws ApiException if fails to make API call
    */
   public String fakeOuterStringSerialize(String body) throws ApiException {
@@ -235,7 +235,7 @@ public class FakeApi {
    * To test \"client\" model
    * To test \"client\" model
    * @param client client model (required)
-   * @return Client
+   * @return a {@code Client}
    * @throws ApiException if fails to make API call
    */
   public Client testClientModel(Client client) throws ApiException {

samples/client/petstore/java/resteasy/src/main/java/org/openapitools/client/api/FakeClassnameTags123Api.java

@@ -38,7 +38,7 @@ public class FakeClassnameTags123Api {
    * To test class name in snake case
    * To test class name in snake case
    * @param client client model (required)
-   * @return Client
+   * @return a {@code Client}
    * @throws ApiException if fails to make API call
    */
   public Client testClassname(Client client) throws ApiException {

samples/client/petstore/java/resteasy/src/main/java/org/openapitools/client/api/PetApi.java

@@ -124,7 +124,7 @@ public class PetApi {
    * Finds Pets by status
    * Multiple status values can be provided with comma separated strings
    * @param status Status values that need to be considered for filter (required)
-   * @return List<Pet>
+   * @return a {@code List<Pet>}
    * @throws ApiException if fails to make API call
    */
   public List<Pet> findPetsByStatus(List<String> status) throws ApiException {
@@ -166,7 +166,7 @@ public class PetApi {
    * Finds Pets by tags
    * Multiple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing.
    * @param tags Tags to filter by (required)
-   * @return List<Pet>
+   * @return a {@code List<Pet>}
    * @throws ApiException if fails to make API call
    * @deprecated
    */
@@ -210,7 +210,7 @@ public class PetApi {
    * Find pet by ID
    * Returns a single pet
    * @param petId ID of pet to return (required)
-   * @return Pet
+   * @return a {@code Pet}
    * @throws ApiException if fails to make API call
    */
   public Pet getPetById(Long petId) throws ApiException {
@@ -341,7 +341,7 @@ if (status != null)
    * @param petId ID of pet to update (required)
    * @param additionalMetadata Additional data to pass to server (optional, default to null)
    * @param file file to upload (optional, default to null)
-   * @return ModelApiResponse
+   * @return a {@code ModelApiResponse}
    * @throws ApiException if fails to make API call
    */
   public ModelApiResponse uploadFile(Long petId, String additionalMetadata, File file) throws ApiException {

samples/client/petstore/java/resteasy/src/main/java/org/openapitools/client/api/StoreApi.java

@@ -78,7 +78,7 @@ public class StoreApi {
   /**
    * Returns pet inventories by status
    * Returns a map of status codes to quantities
-   * @return Map<String, Integer>
+   * @return a {@code Map<String, Integer>}
    * @throws ApiException if fails to make API call
    */
   public Map<String, Integer> getInventory() throws ApiException {
@@ -114,7 +114,7 @@ public class StoreApi {
    * Find purchase order by ID
    * For valid response try integer IDs with value &lt;&#x3D; 5 or &gt; 10. Other values will generated exceptions
    * @param orderId ID of pet that needs to be fetched (required)
-   * @return Order
+   * @return a {@code Order}
    * @throws ApiException if fails to make API call
    */
   public Order getOrderById(Long orderId) throws ApiException {
@@ -156,7 +156,7 @@ public class StoreApi {
    * Place an order for a pet
    * 
    * @param order order placed for purchasing the pet (required)
-   * @return Order
+   * @return a {@code Order}
    * @throws ApiException if fails to make API call
    */
   public Order placeOrder(Order order) throws ApiException {

samples/client/petstore/java/resteasy/src/main/java/org/openapitools/client/api/UserApi.java

@@ -199,7 +199,7 @@ public class UserApi {
    * Get user by user name
    * 
    * @param username The name that needs to be fetched. Use user1 for testing. (required)
-   * @return User
+   * @return a {@code User}
    * @throws ApiException if fails to make API call
    */
   public User getUserByName(String username) throws ApiException {
@@ -242,7 +242,7 @@ public class UserApi {
    * 
    * @param username The user name for login (required)
    * @param password The password for login in clear text (required)
-   * @return String
+   * @return a {@code String}
    * @throws ApiException if fails to make API call
    */
   public String loginUser(String username, String password) throws ApiException {