Add javadoc to spring API, controller and delegate (#4693)

* Add javadoc to spring API, controller and delegate

* Add response description and code in javadoc

samples/server/petstore/spring-mvc-j8-async/src/main/java/org/openapitools/api/AnotherFakeApi.java

@@ -36,6 +36,13 @@ public interface AnotherFakeApi {
         return Optional.empty();
     }
 
+    /**
+     * PATCH /another-fake/dummy : To test special tags
+     * To test special tags and operation ID starting with number
+     *
+     * @param body client model (required)
+     * @return successful operation (status code 200)
+     */
     @ApiOperation(value = "To test special tags", nickname = "call123testSpecialTags", notes = "To test special tags and operation ID starting with number", response = Client.class, tags={ "$another-fake?", })
     @ApiResponses(value = { 
         @ApiResponse(code = 200, message = "successful operation", response = Client.class) })

samples/server/petstore/spring-mvc-j8-async/src/main/java/org/openapitools/api/FakeApi.java

@@ -46,6 +46,13 @@ public interface FakeApi {
         return Optional.empty();
     }
 
+    /**
+     * POST /fake/create_xml_item : creates an XmlItem
+     * this route creates an XmlItem
+     *
+     * @param xmlItem XmlItem Body (required)
+     * @return successful operation (status code 200)
+     */
     @ApiOperation(value = "creates an XmlItem", nickname = "createXmlItem", notes = "this route creates an XmlItem", tags={ "fake", })
     @ApiResponses(value = { 
         @ApiResponse(code = 200, message = "successful operation") })
@@ -58,6 +65,13 @@ public interface FakeApi {
     }
 
 
+    /**
+     * POST /fake/outer/boolean
+     * Test serialization of outer boolean types
+     *
+     * @param body Input boolean as post body (optional)
+     * @return Output boolean (status code 200)
+     */
     @ApiOperation(value = "", nickname = "fakeOuterBooleanSerialize", notes = "Test serialization of outer boolean types", response = Boolean.class, tags={ "fake", })
     @ApiResponses(value = { 
         @ApiResponse(code = 200, message = "Output boolean", response = Boolean.class) })
@@ -70,6 +84,13 @@ public interface FakeApi {
     }
 
 
+    /**
+     * POST /fake/outer/composite
+     * Test serialization of object with outer number type
+     *
+     * @param body Input composite as post body (optional)
+     * @return Output composite (status code 200)
+     */
     @ApiOperation(value = "", nickname = "fakeOuterCompositeSerialize", notes = "Test serialization of object with outer number type", response = OuterComposite.class, tags={ "fake", })
     @ApiResponses(value = { 
         @ApiResponse(code = 200, message = "Output composite", response = OuterComposite.class) })
@@ -93,6 +114,13 @@ public interface FakeApi {
     }
 
 
+    /**
+     * POST /fake/outer/number
+     * Test serialization of outer number types
+     *
+     * @param body Input number as post body (optional)
+     * @return Output number (status code 200)
+     */
     @ApiOperation(value = "", nickname = "fakeOuterNumberSerialize", notes = "Test serialization of outer number types", response = BigDecimal.class, tags={ "fake", })
     @ApiResponses(value = { 
         @ApiResponse(code = 200, message = "Output number", response = BigDecimal.class) })
@@ -105,6 +133,13 @@ public interface FakeApi {
     }
 
 
+    /**
+     * POST /fake/outer/string
+     * Test serialization of outer string types
+     *
+     * @param body Input string as post body (optional)
+     * @return Output string (status code 200)
+     */
     @ApiOperation(value = "", nickname = "fakeOuterStringSerialize", notes = "Test serialization of outer string types", response = String.class, tags={ "fake", })
     @ApiResponses(value = { 
         @ApiResponse(code = 200, message = "Output string", response = String.class) })
@@ -117,6 +152,13 @@ public interface FakeApi {
     }
 
 
+    /**
+     * PUT /fake/body-with-file-schema
+     * For this test, the body for this request much reference a schema named `File`.
+     *
+     * @param body  (required)
+     * @return Success (status code 200)
+     */
     @ApiOperation(value = "", nickname = "testBodyWithFileSchema", notes = "For this test, the body for this request much reference a schema named `File`.", tags={ "fake", })
     @ApiResponses(value = { 
         @ApiResponse(code = 200, message = "Success") })
@@ -129,6 +171,13 @@ public interface FakeApi {
     }
 
 
+    /**
+     * PUT /fake/body-with-query-params
+     *
+     * @param query  (required)
+     * @param body  (required)
+     * @return Success (status code 200)
+     */
     @ApiOperation(value = "", nickname = "testBodyWithQueryParams", notes = "", tags={ "fake", })
     @ApiResponses(value = { 
         @ApiResponse(code = 200, message = "Success") })
@@ -141,6 +190,13 @@ public interface FakeApi {
     }
 
 
+    /**
+     * PATCH /fake : To test \"client\" model
+     * To test \"client\" model
+     *
+     * @param body client model (required)
+     * @return successful operation (status code 200)
+     */
     @ApiOperation(value = "To test \"client\" model", nickname = "testClientModel", notes = "To test \"client\" model", response = Client.class, tags={ "fake", })
     @ApiResponses(value = { 
         @ApiResponse(code = 200, message = "successful operation", response = Client.class) })
@@ -165,6 +221,27 @@ public interface FakeApi {
     }
 
 
+    /**
+     * POST /fake : Fake endpoint for testing various parameters 假端點 偽のエンドポイント 가짜 엔드 포인트 
+     * Fake endpoint for testing various parameters 假端點 偽のエンドポイント 가짜 엔드 포인트 
+     *
+     * @param number None (required)
+     * @param _double None (required)
+     * @param patternWithoutDelimiter None (required)
+     * @param _byte None (required)
+     * @param integer None (optional)
+     * @param int32 None (optional)
+     * @param int64 None (optional)
+     * @param _float None (optional)
+     * @param string None (optional)
+     * @param binary None (optional)
+     * @param date None (optional)
+     * @param dateTime None (optional)
+     * @param password None (optional)
+     * @param paramCallback None (optional)
+     * @return Invalid username supplied (status code 400)
+     *         or User not found (status code 404)
+     */
     @ApiOperation(value = "Fake endpoint for testing various parameters 假端點 偽のエンドポイント 가짜 엔드 포인트 ", nickname = "testEndpointParameters", notes = "Fake endpoint for testing various parameters 假端點 偽のエンドポイント 가짜 엔드 포인트 ", authorizations = {
         @Authorization(value = "http_basic_test")
     }, tags={ "fake", })
@@ -180,6 +257,21 @@ public interface FakeApi {
     }
 
 
+    /**
+     * GET /fake : To test enum parameters
+     * To test enum parameters
+     *
+     * @param enumHeaderStringArray Header parameter enum test (string array) (optional, default to new ArrayList<>())
+     * @param enumHeaderString Header parameter enum test (string) (optional, default to -efg)
+     * @param enumQueryStringArray Query parameter enum test (string array) (optional, default to new ArrayList<>())
+     * @param enumQueryString Query parameter enum test (string) (optional, default to -efg)
+     * @param enumQueryInteger Query parameter enum test (double) (optional)
+     * @param enumQueryDouble Query parameter enum test (double) (optional)
+     * @param enumFormStringArray Form parameter enum test (string array) (optional, default to $)
+     * @param enumFormString Form parameter enum test (string) (optional, default to -efg)
+     * @return Invalid request (status code 400)
+     *         or Not found (status code 404)
+     */
     @ApiOperation(value = "To test enum parameters", nickname = "testEnumParameters", notes = "To test enum parameters", tags={ "fake", })
     @ApiResponses(value = { 
         @ApiResponse(code = 400, message = "Invalid request"),
@@ -193,6 +285,18 @@ public interface FakeApi {
     }
 
 
+    /**
+     * DELETE /fake : Fake endpoint to test group parameters (optional)
+     * Fake endpoint to test group parameters (optional)
+     *
+     * @param requiredStringGroup Required String in group parameters (required)
+     * @param requiredBooleanGroup Required Boolean in group parameters (required)
+     * @param requiredInt64Group Required Integer in group parameters (required)
+     * @param stringGroup String in group parameters (optional)
+     * @param booleanGroup Boolean in group parameters (optional)
+     * @param int64Group Integer in group parameters (optional)
+     * @return Someting wrong (status code 400)
+     */
     @ApiOperation(value = "Fake endpoint to test group parameters (optional)", nickname = "testGroupParameters", notes = "Fake endpoint to test group parameters (optional)", tags={ "fake", })
     @ApiResponses(value = { 
         @ApiResponse(code = 400, message = "Someting wrong") })
@@ -204,6 +308,12 @@ public interface FakeApi {
     }
 
 
+    /**
+     * POST /fake/inline-additionalProperties : test inline additionalProperties
+     *
+     * @param param request body (required)
+     * @return successful operation (status code 200)
+     */
     @ApiOperation(value = "test inline additionalProperties", nickname = "testInlineAdditionalProperties", notes = "", tags={ "fake", })
     @ApiResponses(value = { 
         @ApiResponse(code = 200, message = "successful operation") })
@@ -216,6 +326,13 @@ public interface FakeApi {
     }
 
 
+    /**
+     * GET /fake/jsonFormData : test json serialization of form data
+     *
+     * @param param field1 (required)
+     * @param param2 field2 (required)
+     * @return successful operation (status code 200)
+     */
     @ApiOperation(value = "test json serialization of form data", nickname = "testJsonFormData", notes = "", tags={ "fake", })
     @ApiResponses(value = { 
         @ApiResponse(code = 200, message = "successful operation") })
@@ -228,6 +345,17 @@ public interface FakeApi {
     }
 
 
+    /**
+     * PUT /fake/test-query-paramters
+     * To test the collection format in query parameters
+     *
+     * @param pipe  (required)
+     * @param ioutil  (required)
+     * @param http  (required)
+     * @param url  (required)
+     * @param context  (required)
+     * @return Success (status code 200)
+     */
     @ApiOperation(value = "", nickname = "testQueryParameterCollectionFormat", notes = "To test the collection format in query parameters", tags={ "fake", })
     @ApiResponses(value = { 
         @ApiResponse(code = 200, message = "Success") })
@@ -239,6 +367,14 @@ public interface FakeApi {
     }
 
 
+    /**
+     * POST /fake/{petId}/uploadImageWithRequiredFile : uploads an image (required)
+     *
+     * @param petId ID of pet to update (required)
+     * @param requiredFile file to upload (required)
+     * @param additionalMetadata Additional data to pass to server (optional)
+     * @return successful operation (status code 200)
+     */
     @ApiOperation(value = "uploads an image (required)", nickname = "uploadFileWithRequiredFile", notes = "", response = ModelApiResponse.class, authorizations = {
         @Authorization(value = "petstore_auth", scopes = {
             @AuthorizationScope(scope = "write:pets", description = "modify pets in your account"),

samples/server/petstore/spring-mvc-j8-async/src/main/java/org/openapitools/api/FakeClassnameTestApi.java

@@ -36,6 +36,13 @@ public interface FakeClassnameTestApi {
         return Optional.empty();
     }
 
+    /**
+     * PATCH /fake_classname_test : To test class name in snake case
+     * To test class name in snake case
+     *
+     * @param body client model (required)
+     * @return successful operation (status code 200)
+     */
     @ApiOperation(value = "To test class name in snake case", nickname = "testClassname", notes = "To test class name in snake case", response = Client.class, authorizations = {
         @Authorization(value = "api_key_query")
     }, tags={ "fake_classname_tags 123#$%^", })

samples/server/petstore/spring-mvc-j8-async/src/main/java/org/openapitools/api/PetApi.java

@@ -38,6 +38,13 @@ public interface PetApi {
         return Optional.empty();
     }
 
+    /**
+     * POST /pet : Add a new pet to the store
+     *
+     * @param body Pet object that needs to be added to the store (required)
+     * @return successful operation (status code 200)
+     *         or Invalid input (status code 405)
+     */
     @ApiOperation(value = "Add a new pet to the store", nickname = "addPet", notes = "", authorizations = {
         @Authorization(value = "petstore_auth", scopes = {
             @AuthorizationScope(scope = "write:pets", description = "modify pets in your account"),
@@ -56,6 +63,14 @@ public interface PetApi {
     }
 
 
+    /**
+     * DELETE /pet/{petId} : Deletes a pet
+     *
+     * @param petId Pet id to delete (required)
+     * @param apiKey  (optional)
+     * @return successful operation (status code 200)
+     *         or Invalid pet value (status code 400)
+     */
     @ApiOperation(value = "Deletes a pet", nickname = "deletePet", notes = "", authorizations = {
         @Authorization(value = "petstore_auth", scopes = {
             @AuthorizationScope(scope = "write:pets", description = "modify pets in your account"),
@@ -73,6 +88,14 @@ public interface PetApi {
     }
 
 
+    /**
+     * GET /pet/findByStatus : 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 successful operation (status code 200)
+     *         or Invalid status value (status code 400)
+     */
     @ApiOperation(value = "Finds Pets by status", nickname = "findPetsByStatus", notes = "Multiple status values can be provided with comma separated strings", response = Pet.class, responseContainer = "List", authorizations = {
         @Authorization(value = "petstore_auth", scopes = {
             @AuthorizationScope(scope = "write:pets", description = "modify pets in your account"),
@@ -107,6 +130,15 @@ public interface PetApi {
     }
 
 
+    /**
+     * GET /pet/findByTags : 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 successful operation (status code 200)
+     *         or Invalid tag value (status code 400)
+     * @deprecated
+     */
     @ApiOperation(value = "Finds Pets by tags", nickname = "findPetsByTags", notes = "Multiple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing.", response = Pet.class, responseContainer = "List", authorizations = {
         @Authorization(value = "petstore_auth", scopes = {
             @AuthorizationScope(scope = "write:pets", description = "modify pets in your account"),
@@ -141,6 +173,15 @@ public interface PetApi {
     }
 
 
+    /**
+     * GET /pet/{petId} : Find pet by ID
+     * Returns a single pet
+     *
+     * @param petId ID of pet to return (required)
+     * @return successful operation (status code 200)
+     *         or Invalid ID supplied (status code 400)
+     *         or Pet not found (status code 404)
+     */
     @ApiOperation(value = "Find pet by ID", nickname = "getPetById", notes = "Returns a single pet", response = Pet.class, authorizations = {
         @Authorization(value = "api_key")
     }, tags={ "pet", })
@@ -173,6 +214,15 @@ public interface PetApi {
     }
 
 
+    /**
+     * PUT /pet : Update an existing pet
+     *
+     * @param body Pet object that needs to be added to the store (required)
+     * @return successful operation (status code 200)
+     *         or Invalid ID supplied (status code 400)
+     *         or Pet not found (status code 404)
+     *         or Validation exception (status code 405)
+     */
     @ApiOperation(value = "Update an existing pet", nickname = "updatePet", notes = "", authorizations = {
         @Authorization(value = "petstore_auth", scopes = {
             @AuthorizationScope(scope = "write:pets", description = "modify pets in your account"),
@@ -193,6 +243,14 @@ public interface PetApi {
     }
 
 
+    /**
+     * POST /pet/{petId} : Updates a pet in the store with form data
+     *
+     * @param petId ID of pet that needs to be updated (required)
+     * @param name Updated name of the pet (optional)
+     * @param status Updated status of the pet (optional)
+     * @return Invalid input (status code 405)
+     */
     @ApiOperation(value = "Updates a pet in the store with form data", nickname = "updatePetWithForm", notes = "", authorizations = {
         @Authorization(value = "petstore_auth", scopes = {
             @AuthorizationScope(scope = "write:pets", description = "modify pets in your account"),
@@ -210,6 +268,14 @@ public interface PetApi {
     }
 
 
+    /**
+     * POST /pet/{petId}/uploadImage : uploads an image
+     *
+     * @param petId ID of pet to update (required)
+     * @param additionalMetadata Additional data to pass to server (optional)
+     * @param file file to upload (optional)
+     * @return successful operation (status code 200)
+     */
     @ApiOperation(value = "uploads an image", nickname = "uploadFile", notes = "", response = ModelApiResponse.class, authorizations = {
         @Authorization(value = "petstore_auth", scopes = {
             @AuthorizationScope(scope = "write:pets", description = "modify pets in your account"),

samples/server/petstore/spring-mvc-j8-async/src/main/java/org/openapitools/api/StoreApi.java

@@ -37,6 +37,14 @@ public interface StoreApi {
         return Optional.empty();
     }
 
+    /**
+     * DELETE /store/order/{order_id} : Delete purchase order by ID
+     * For valid response try integer IDs with value < 1000. Anything above 1000 or nonintegers will generate API errors
+     *
+     * @param orderId ID of the order that needs to be deleted (required)
+     * @return Invalid ID supplied (status code 400)
+     *         or Order not found (status code 404)
+     */
     @ApiOperation(value = "Delete purchase order by ID", nickname = "deleteOrder", notes = "For valid response try integer IDs with value < 1000. Anything above 1000 or nonintegers will generate API errors", tags={ "store", })
     @ApiResponses(value = { 
         @ApiResponse(code = 400, message = "Invalid ID supplied"),
@@ -49,6 +57,12 @@ public interface StoreApi {
     }
 
 
+    /**
+     * GET /store/inventory : Returns pet inventories by status
+     * Returns a map of status codes to quantities
+     *
+     * @return successful operation (status code 200)
+     */
     @ApiOperation(value = "Returns pet inventories by status", nickname = "getInventory", notes = "Returns a map of status codes to quantities", response = Integer.class, responseContainer = "Map", authorizations = {
         @Authorization(value = "api_key")
     }, tags={ "store", })
@@ -63,6 +77,15 @@ public interface StoreApi {
     }
 
 
+    /**
+     * GET /store/order/{order_id} : 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 successful operation (status code 200)
+     *         or Invalid ID supplied (status code 400)
+     *         or Order not found (status code 404)
+     */
     @ApiOperation(value = "Find purchase order by ID", nickname = "getOrderById", notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions", response = Order.class, tags={ "store", })
     @ApiResponses(value = { 
         @ApiResponse(code = 200, message = "successful operation", response = Order.class),
@@ -93,6 +116,13 @@ public interface StoreApi {
     }
 
 
+    /**
+     * POST /store/order : Place an order for a pet
+     *
+     * @param body order placed for purchasing the pet (required)
+     * @return successful operation (status code 200)
+     *         or Invalid Order (status code 400)
+     */
     @ApiOperation(value = "Place an order for a pet", nickname = "placeOrder", notes = "", response = Order.class, tags={ "store", })
     @ApiResponses(value = { 
         @ApiResponse(code = 200, message = "successful operation", response = Order.class),

samples/server/petstore/spring-mvc-j8-async/src/main/java/org/openapitools/api/UserApi.java

@@ -37,6 +37,13 @@ public interface UserApi {
         return Optional.empty();
     }
 
+    /**
+     * POST /user : Create user
+     * This can only be done by the logged in user.
+     *
+     * @param body Created user object (required)
+     * @return successful operation (status code 200)
+     */
     @ApiOperation(value = "Create user", nickname = "createUser", notes = "This can only be done by the logged in user.", tags={ "user", })
     @ApiResponses(value = { 
         @ApiResponse(code = 200, message = "successful operation") })
@@ -48,6 +55,12 @@ public interface UserApi {
     }
 
 
+    /**
+     * POST /user/createWithArray : Creates list of users with given input array
+     *
+     * @param body List of user object (required)
+     * @return successful operation (status code 200)
+     */
     @ApiOperation(value = "Creates list of users with given input array", nickname = "createUsersWithArrayInput", notes = "", tags={ "user", })
     @ApiResponses(value = { 
         @ApiResponse(code = 200, message = "successful operation") })
@@ -59,6 +72,12 @@ public interface UserApi {
     }
 
 
+    /**
+     * POST /user/createWithList : Creates list of users with given input array
+     *
+     * @param body List of user object (required)
+     * @return successful operation (status code 200)
+     */
     @ApiOperation(value = "Creates list of users with given input array", nickname = "createUsersWithListInput", notes = "", tags={ "user", })
     @ApiResponses(value = { 
         @ApiResponse(code = 200, message = "successful operation") })
@@ -70,6 +89,14 @@ public interface UserApi {
     }
 
 
+    /**
+     * DELETE /user/{username} : Delete user
+     * This can only be done by the logged in user.
+     *
+     * @param username The name that needs to be deleted (required)
+     * @return Invalid username supplied (status code 400)
+     *         or User not found (status code 404)
+     */
     @ApiOperation(value = "Delete user", nickname = "deleteUser", notes = "This can only be done by the logged in user.", tags={ "user", })
     @ApiResponses(value = { 
         @ApiResponse(code = 400, message = "Invalid username supplied"),
@@ -82,6 +109,14 @@ public interface UserApi {
     }
 
 
+    /**
+     * GET /user/{username} : Get user by user name
+     *
+     * @param username The name that needs to be fetched. Use user1 for testing. (required)
+     * @return successful operation (status code 200)
+     *         or Invalid username supplied (status code 400)
+     *         or User not found (status code 404)
+     */
     @ApiOperation(value = "Get user by user name", nickname = "getUserByName", notes = "", response = User.class, tags={ "user", })
     @ApiResponses(value = { 
         @ApiResponse(code = 200, message = "successful operation", response = User.class),
@@ -112,6 +147,14 @@ public interface UserApi {
     }
 
 
+    /**
+     * GET /user/login : Logs user into the system
+     *
+     * @param username The user name for login (required)
+     * @param password The password for login in clear text (required)
+     * @return successful operation (status code 200)
+     *         or Invalid username/password supplied (status code 400)
+     */
     @ApiOperation(value = "Logs user into the system", nickname = "loginUser", notes = "", response = String.class, tags={ "user", })
     @ApiResponses(value = { 
         @ApiResponse(code = 200, message = "successful operation", response = String.class),
@@ -125,6 +168,11 @@ public interface UserApi {
     }
 
 
+    /**
+     * GET /user/logout : Logs out current logged in user session
+     *
+     * @return successful operation (status code 200)
+     */
     @ApiOperation(value = "Logs out current logged in user session", nickname = "logoutUser", notes = "", tags={ "user", })
     @ApiResponses(value = { 
         @ApiResponse(code = 200, message = "successful operation") })
@@ -136,6 +184,15 @@ public interface UserApi {
     }
 
 
+    /**
+     * PUT /user/{username} : Updated user
+     * This can only be done by the logged in user.
+     *
+     * @param username name that need to be deleted (required)
+     * @param body Updated user object (required)
+     * @return Invalid user supplied (status code 400)
+     *         or User not found (status code 404)
+     */
     @ApiOperation(value = "Updated user", nickname = "updateUser", notes = "This can only be done by the logged in user.", tags={ "user", })
     @ApiResponses(value = { 
         @ApiResponse(code = 400, message = "Invalid user supplied"),