[Java][Rest-assured] Fix generated javadoc and "swagger-annotations" improvement (#831)

Added "@Api" swagger annotation, "nickname" for ApiOperation. 
Fixed javadock for rest-assured client.

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

@@ -28,6 +28,7 @@ import {{invokerPackage}}.JSON;
 
 import static io.restassured.http.Method.*;
 
+@Api(value = "{{{baseName}}}")
 public class {{classname}} {
 
     private RequestSpecBuilder reqSpec;
@@ -45,6 +46,7 @@ public class {{classname}} {
 
     @ApiOperation(value = "{{{summary}}}",
             notes = "{{{notes}}}",
+            nickname = "{{{operationId}}}",
             tags = { {{#tags}}{{#name}}"{{{name}}}"{{/name}}{{^-last}}, {{/-last}}{{/tags}} })
     @ApiResponses(value = { {{#responses}}
             @ApiResponse(code = {{{code}}}, message = "{{{message}}}") {{#hasMore}},{{/hasMore}}{{/responses}} })
@@ -135,7 +137,7 @@ public class {{classname}} {
         {{#bodyParams}}
 
          /**
-         * @param {{paramName}} ({{{dataType}}}) {{description}}{{#required}} (required){{/required}}{{^required}} (optional{{#defaultValue}}, default to {{.}}{{/defaultValue}}){{/required}}
+         * @param {{paramName}} ({{dataType}}) {{description}}{{#required}} (required){{/required}}{{^required}} (optional{{#defaultValue}}, default to {{.}}{{/defaultValue}}){{/required}}
          * @return operation
          */
         public {{operationIdCamelCase}}Oper body({{{dataType}}} {{paramName}}) {
@@ -148,7 +150,7 @@ public class {{classname}} {
         public static final String {{#convert}}{{paramName}}{{/convert}}_HEADER = "{{baseName}}";
 
         /**
-         * @param {{paramName}} ({{{dataType}}}) {{description}}{{#required}} (required){{/required}}{{^required}} (optional{{#defaultValue}}, default to {{.}}{{/defaultValue}}){{/required}}
+         * @param {{paramName}} ({{dataType}}) {{description}}{{#required}} (required){{/required}}{{^required}} (optional{{#defaultValue}}, default to {{.}}{{/defaultValue}}){{/required}}
          * @return operation
          */
         public {{operationIdCamelCase}}Oper {{paramName}}Header(String {{paramName}}) {
@@ -161,7 +163,7 @@ public class {{classname}} {
         public static final String {{#convert}}{{paramName}}{{/convert}}_PATH = "{{baseName}}";
 
         /**
-         * @param {{paramName}} ({{{dataType}}}) {{description}}{{#required}} (required){{/required}}{{^required}} (optional{{#defaultValue}}, default to {{.}}{{/defaultValue}}){{/required}}
+         * @param {{paramName}} ({{dataType}}) {{description}}{{#required}} (required){{/required}}{{^required}} (optional{{#defaultValue}}, default to {{.}}{{/defaultValue}}){{/required}}
          * @return operation
          */
         public {{operationIdCamelCase}}Oper {{paramName}}Path(Object {{paramName}}) {
@@ -174,7 +176,7 @@ public class {{classname}} {
         public static final String {{#convert}}{{paramName}}{{/convert}}_QUERY = "{{baseName}}";
 
         /**
-         * @param {{paramName}} ({{{dataType}}}) {{description}}{{#required}} (required){{/required}}{{^required}} (optional{{#defaultValue}}, default to {{.}}{{/defaultValue}}){{/required}}
+         * @param {{paramName}} ({{dataType}}) {{description}}{{#required}} (required){{/required}}{{^required}} (optional{{#defaultValue}}, default to {{.}}{{/defaultValue}}){{/required}}
          * @return operation
          */
         public {{operationIdCamelCase}}Oper {{paramName}}Query(Object... {{paramName}}) {
@@ -188,7 +190,7 @@ public class {{classname}} {
          public static final String {{#convert}}{{paramName}}{{/convert}}_FORM = "{{baseName}}";
 
          /**
-         * @param {{paramName}} ({{{dataType}}}) {{description}}{{#required}} (required){{/required}}{{^required}} (optional{{#defaultValue}}, default to {{.}}{{/defaultValue}}){{/required}}
+         * @param {{paramName}} ({{dataType}}) {{description}}{{#required}} (required){{/required}}{{^required}} (optional{{#defaultValue}}, default to {{.}}{{/defaultValue}}){{/required}}
          * @return operation
          */
          public {{operationIdCamelCase}}Oper {{paramName}}Form(Object... {{paramName}}) {
@@ -203,7 +205,7 @@ public class {{classname}} {
          /**
          * It will assume that the control name is file and the <content-type> is <application/octet-stream>
          * @see #reqSpec for customise
-         * @param {{paramName}} ({{{dataType}}}) {{description}}{{#required}} (required){{/required}}{{^required}} (optional{{#defaultValue}}, default to {{.}}{{/defaultValue}}){{/required}}
+         * @param {{paramName}} ({{dataType}}) {{description}}{{#required}} (required){{/required}}{{^required}} (optional{{#defaultValue}}, default to {{.}}{{/defaultValue}}){{/required}}
          * @return operation
          */
          public {{operationIdCamelCase}}Oper {{paramName}}MultiPart({{{dataType}}} {{paramName}}) {

samples/client/petstore/java/rest-assured/src/main/java/org/openapitools/client/api/AnotherFakeApi.java

@@ -36,6 +36,7 @@ import org.openapitools.client.JSON;
 
 import static io.restassured.http.Method.*;
 
+@Api(value = "AnotherFake")
 public class AnotherFakeApi {
 
     private RequestSpecBuilder reqSpec;
@@ -51,6 +52,7 @@ public class AnotherFakeApi {
 
     @ApiOperation(value = "To test special tags",
             notes = "To test special tags and operation ID starting with number",
+            nickname = "call123testSpecialTags",
             tags = { "$another-fake?" })
     @ApiResponses(value = { 
             @ApiResponse(code = 200, message = "successful operation")  })

samples/client/petstore/java/rest-assured/src/main/java/org/openapitools/client/api/FakeApi.java

@@ -43,6 +43,7 @@ import org.openapitools.client.JSON;
 
 import static io.restassured.http.Method.*;
 
+@Api(value = "Fake")
 public class FakeApi {
 
     private RequestSpecBuilder reqSpec;
@@ -58,6 +59,7 @@ public class FakeApi {
 
     @ApiOperation(value = "",
             notes = "Test serialization of outer boolean types",
+            nickname = "fakeOuterBooleanSerialize",
             tags = { "fake" })
     @ApiResponses(value = { 
             @ApiResponse(code = 200, message = "Output boolean")  })
@@ -67,6 +69,7 @@ public class FakeApi {
 
     @ApiOperation(value = "",
             notes = "Test serialization of object with outer number type",
+            nickname = "fakeOuterCompositeSerialize",
             tags = { "fake" })
     @ApiResponses(value = { 
             @ApiResponse(code = 200, message = "Output composite")  })
@@ -76,6 +79,7 @@ public class FakeApi {
 
     @ApiOperation(value = "",
             notes = "Test serialization of outer number types",
+            nickname = "fakeOuterNumberSerialize",
             tags = { "fake" })
     @ApiResponses(value = { 
             @ApiResponse(code = 200, message = "Output number")  })
@@ -85,6 +89,7 @@ public class FakeApi {
 
     @ApiOperation(value = "",
             notes = "Test serialization of outer string types",
+            nickname = "fakeOuterStringSerialize",
             tags = { "fake" })
     @ApiResponses(value = { 
             @ApiResponse(code = 200, message = "Output string")  })
@@ -94,6 +99,7 @@ public class FakeApi {
 
     @ApiOperation(value = "",
             notes = "For this test, the body for this request much reference a schema named `File`.",
+            nickname = "testBodyWithFileSchema",
             tags = { "fake" })
     @ApiResponses(value = { 
             @ApiResponse(code = 200, message = "Success")  })
@@ -103,6 +109,7 @@ public class FakeApi {
 
     @ApiOperation(value = "",
             notes = "",
+            nickname = "testBodyWithQueryParams",
             tags = { "fake" })
     @ApiResponses(value = { 
             @ApiResponse(code = 200, message = "Success")  })
@@ -112,6 +119,7 @@ public class FakeApi {
 
     @ApiOperation(value = "To test \"client\" model",
             notes = "To test \"client\" model",
+            nickname = "testClientModel",
             tags = { "fake" })
     @ApiResponses(value = { 
             @ApiResponse(code = 200, message = "successful operation")  })
@@ -121,6 +129,7 @@ public class FakeApi {
 
     @ApiOperation(value = "Fake endpoint for testing various parameters 假端點 偽のエンドポイント 가짜 엔드 포인트 ",
             notes = "Fake endpoint for testing various parameters 假端點 偽のエンドポイント 가짜 엔드 포인트 ",
+            nickname = "testEndpointParameters",
             tags = { "fake" })
     @ApiResponses(value = { 
             @ApiResponse(code = 400, message = "Invalid username supplied") ,
@@ -131,6 +140,7 @@ public class FakeApi {
 
     @ApiOperation(value = "To test enum parameters",
             notes = "To test enum parameters",
+            nickname = "testEnumParameters",
             tags = { "fake" })
     @ApiResponses(value = { 
             @ApiResponse(code = 400, message = "Invalid request") ,
@@ -141,6 +151,7 @@ public class FakeApi {
 
     @ApiOperation(value = "test inline additionalProperties",
             notes = "",
+            nickname = "testInlineAdditionalProperties",
             tags = { "fake" })
     @ApiResponses(value = { 
             @ApiResponse(code = 200, message = "successful operation")  })
@@ -150,6 +161,7 @@ public class FakeApi {
 
     @ApiOperation(value = "test json serialization of form data",
             notes = "",
+            nickname = "testJsonFormData",
             tags = { "fake" })
     @ApiResponses(value = { 
             @ApiResponse(code = 200, message = "successful operation")  })
@@ -913,7 +925,7 @@ public class FakeApi {
         public static final String ENUM_HEADER_STRING_ARRAY_HEADER = "enum_header_string_array";
 
         /**
-         * @param enumHeaderStringArray (List<String>) Header parameter enum test (string array) (optional)
+         * @param enumHeaderStringArray (List&lt;String&gt;) Header parameter enum test (string array) (optional)
          * @return operation
          */
         public TestEnumParametersOper enumHeaderStringArrayHeader(String enumHeaderStringArray) {
@@ -935,7 +947,7 @@ public class FakeApi {
         public static final String ENUM_QUERY_STRING_ARRAY_QUERY = "enum_query_string_array";
 
         /**
-         * @param enumQueryStringArray (List<String>) Query parameter enum test (string array) (optional)
+         * @param enumQueryStringArray (List&lt;String&gt;) Query parameter enum test (string array) (optional)
          * @return operation
          */
         public TestEnumParametersOper enumQueryStringArrayQuery(Object... enumQueryStringArray) {
@@ -979,7 +991,7 @@ public class FakeApi {
          public static final String ENUM_FORM_STRING_ARRAY_FORM = "enum_form_string_array";
 
          /**
-         * @param enumFormStringArray (List<String>) Form parameter enum test (string array) (optional, default to $)
+         * @param enumFormStringArray (List&lt;String&gt;) Form parameter enum test (string array) (optional, default to $)
          * @return operation
          */
          public TestEnumParametersOper enumFormStringArrayForm(Object... enumFormStringArray) {
@@ -1050,7 +1062,7 @@ public class FakeApi {
         }
 
          /**
-         * @param requestBody (Map<String, String>) request body (required)
+         * @param requestBody (Map&lt;String, String&gt;) request body (required)
          * @return operation
          */
         public TestInlineAdditionalPropertiesOper body(Map<String, String> requestBody) {

samples/client/petstore/java/rest-assured/src/main/java/org/openapitools/client/api/FakeClassnameTags123Api.java

@@ -36,6 +36,7 @@ import org.openapitools.client.JSON;
 
 import static io.restassured.http.Method.*;
 
+@Api(value = "FakeClassnameTags123")
 public class FakeClassnameTags123Api {
 
     private RequestSpecBuilder reqSpec;
@@ -51,6 +52,7 @@ public class FakeClassnameTags123Api {
 
     @ApiOperation(value = "To test class name in snake case",
             notes = "To test class name in snake case",
+            nickname = "testClassname",
             tags = { "fake_classname_tags 123#$%^" })
     @ApiResponses(value = { 
             @ApiResponse(code = 200, message = "successful operation")  })

samples/client/petstore/java/rest-assured/src/main/java/org/openapitools/client/api/PetApi.java

@@ -38,6 +38,7 @@ import org.openapitools.client.JSON;
 
 import static io.restassured.http.Method.*;
 
+@Api(value = "Pet")
 public class PetApi {
 
     private RequestSpecBuilder reqSpec;
@@ -53,6 +54,7 @@ public class PetApi {
 
     @ApiOperation(value = "Add a new pet to the store",
             notes = "",
+            nickname = "addPet",
             tags = { "pet" })
     @ApiResponses(value = { 
             @ApiResponse(code = 405, message = "Invalid input")  })
@@ -62,6 +64,7 @@ public class PetApi {
 
     @ApiOperation(value = "Deletes a pet",
             notes = "",
+            nickname = "deletePet",
             tags = { "pet" })
     @ApiResponses(value = { 
             @ApiResponse(code = 400, message = "Invalid pet value")  })
@@ -71,6 +74,7 @@ public class PetApi {
 
     @ApiOperation(value = "Finds Pets by status",
             notes = "Multiple status values can be provided with comma separated strings",
+            nickname = "findPetsByStatus",
             tags = { "pet" })
     @ApiResponses(value = { 
             @ApiResponse(code = 200, message = "successful operation") ,
@@ -81,6 +85,7 @@ public class PetApi {
 
     @ApiOperation(value = "Finds Pets by tags",
             notes = "Multiple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing.",
+            nickname = "findPetsByTags",
             tags = { "pet" })
     @ApiResponses(value = { 
             @ApiResponse(code = 200, message = "successful operation") ,
@@ -92,6 +97,7 @@ public class PetApi {
 
     @ApiOperation(value = "Find pet by ID",
             notes = "Returns a single pet",
+            nickname = "getPetById",
             tags = { "pet" })
     @ApiResponses(value = { 
             @ApiResponse(code = 200, message = "successful operation") ,
@@ -103,6 +109,7 @@ public class PetApi {
 
     @ApiOperation(value = "Update an existing pet",
             notes = "",
+            nickname = "updatePet",
             tags = { "pet" })
     @ApiResponses(value = { 
             @ApiResponse(code = 400, message = "Invalid ID supplied") ,
@@ -114,6 +121,7 @@ public class PetApi {
 
     @ApiOperation(value = "Updates a pet in the store with form data",
             notes = "",
+            nickname = "updatePetWithForm",
             tags = { "pet" })
     @ApiResponses(value = { 
             @ApiResponse(code = 405, message = "Invalid input")  })
@@ -123,6 +131,7 @@ public class PetApi {
 
     @ApiOperation(value = "uploads an image",
             notes = "",
+            nickname = "uploadFile",
             tags = { "pet" })
     @ApiResponses(value = { 
             @ApiResponse(code = 200, message = "successful operation")  })
@@ -132,6 +141,7 @@ public class PetApi {
 
     @ApiOperation(value = "uploads an image (required)",
             notes = "",
+            nickname = "uploadFileWithRequiredFile",
             tags = { "pet" })
     @ApiResponses(value = { 
             @ApiResponse(code = 200, message = "successful operation")  })
@@ -326,7 +336,7 @@ public class PetApi {
         public static final String STATUS_QUERY = "status";
 
         /**
-         * @param status (List<String>) Status values that need to be considered for filter (required)
+         * @param status (List&lt;String&gt;) Status values that need to be considered for filter (required)
          * @return operation
          */
         public FindPetsByStatusOper statusQuery(Object... status) {
@@ -400,7 +410,7 @@ public class PetApi {
         public static final String TAGS_QUERY = "tags";
 
         /**
-         * @param tags (List<String>) Tags to filter by (required)
+         * @param tags (List&lt;String&gt;) Tags to filter by (required)
          * @return operation
          */
         public FindPetsByTagsOper tagsQuery(Object... tags) {

samples/client/petstore/java/rest-assured/src/main/java/org/openapitools/client/api/StoreApi.java

@@ -36,6 +36,7 @@ import org.openapitools.client.JSON;
 
 import static io.restassured.http.Method.*;
 
+@Api(value = "Store")
 public class StoreApi {
 
     private RequestSpecBuilder reqSpec;
@@ -51,6 +52,7 @@ public class StoreApi {
 
     @ApiOperation(value = "Delete purchase order by ID",
             notes = "For valid response try integer IDs with value < 1000. Anything above 1000 or nonintegers will generate API errors",
+            nickname = "deleteOrder",
             tags = { "store" })
     @ApiResponses(value = { 
             @ApiResponse(code = 400, message = "Invalid ID supplied") ,
@@ -61,6 +63,7 @@ public class StoreApi {
 
     @ApiOperation(value = "Returns pet inventories by status",
             notes = "Returns a map of status codes to quantities",
+            nickname = "getInventory",
             tags = { "store" })
     @ApiResponses(value = { 
             @ApiResponse(code = 200, message = "successful operation")  })
@@ -70,6 +73,7 @@ public class StoreApi {
 
     @ApiOperation(value = "Find purchase order by ID",
             notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions",
+            nickname = "getOrderById",
             tags = { "store" })
     @ApiResponses(value = { 
             @ApiResponse(code = 200, message = "successful operation") ,
@@ -81,6 +85,7 @@ public class StoreApi {
 
     @ApiOperation(value = "Place an order for a pet",
             notes = "",
+            nickname = "placeOrder",
             tags = { "store" })
     @ApiResponses(value = { 
             @ApiResponse(code = 200, message = "successful operation") ,

samples/client/petstore/java/rest-assured/src/main/java/org/openapitools/client/api/UserApi.java

@@ -36,6 +36,7 @@ import org.openapitools.client.JSON;
 
 import static io.restassured.http.Method.*;
 
+@Api(value = "User")
 public class UserApi {
 
     private RequestSpecBuilder reqSpec;
@@ -51,6 +52,7 @@ public class UserApi {
 
     @ApiOperation(value = "Create user",
             notes = "This can only be done by the logged in user.",
+            nickname = "createUser",
             tags = { "user" })
     @ApiResponses(value = { 
             @ApiResponse(code = 0, message = "successful operation")  })
@@ -60,6 +62,7 @@ public class UserApi {
 
     @ApiOperation(value = "Creates list of users with given input array",
             notes = "",
+            nickname = "createUsersWithArrayInput",
             tags = { "user" })
     @ApiResponses(value = { 
             @ApiResponse(code = 0, message = "successful operation")  })
@@ -69,6 +72,7 @@ public class UserApi {
 
     @ApiOperation(value = "Creates list of users with given input array",
             notes = "",
+            nickname = "createUsersWithListInput",
             tags = { "user" })
     @ApiResponses(value = { 
             @ApiResponse(code = 0, message = "successful operation")  })
@@ -78,6 +82,7 @@ public class UserApi {
 
     @ApiOperation(value = "Delete user",
             notes = "This can only be done by the logged in user.",
+            nickname = "deleteUser",
             tags = { "user" })
     @ApiResponses(value = { 
             @ApiResponse(code = 400, message = "Invalid username supplied") ,
@@ -88,6 +93,7 @@ public class UserApi {
 
     @ApiOperation(value = "Get user by user name",
             notes = "",
+            nickname = "getUserByName",
             tags = { "user" })
     @ApiResponses(value = { 
             @ApiResponse(code = 200, message = "successful operation") ,
@@ -99,6 +105,7 @@ public class UserApi {
 
     @ApiOperation(value = "Logs user into the system",
             notes = "",
+            nickname = "loginUser",
             tags = { "user" })
     @ApiResponses(value = { 
             @ApiResponse(code = 200, message = "successful operation") ,
@@ -109,6 +116,7 @@ public class UserApi {
 
     @ApiOperation(value = "Logs out current logged in user session",
             notes = "",
+            nickname = "logoutUser",
             tags = { "user" })
     @ApiResponses(value = { 
             @ApiResponse(code = 0, message = "successful operation")  })
@@ -118,6 +126,7 @@ public class UserApi {
 
     @ApiOperation(value = "Updated user",
             notes = "This can only be done by the logged in user.",
+            nickname = "updateUser",
             tags = { "user" })
     @ApiResponses(value = { 
             @ApiResponse(code = 400, message = "Invalid user supplied") ,
@@ -228,7 +237,7 @@ public class UserApi {
         }
 
          /**
-         * @param user (List<User>) List of user object (required)
+         * @param user (List&lt;User&gt;) List of user object (required)
          * @return operation
          */
         public CreateUsersWithArrayInputOper body(List<User> user) {
@@ -288,7 +297,7 @@ public class UserApi {
         }
 
          /**
-         * @param user (List<User>) List of user object (required)
+         * @param user (List&lt;User&gt;) List of user object (required)
          * @return operation
          */
         public CreateUsersWithListInputOper body(List<User> user) {