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

* Add javadoc to spring API, controller and delegate

* Add response description and code in javadoc

modules/openapi-generator/src/main/resources/JavaSpring/api.mustache

@@ -84,6 +84,25 @@ public interface {{classname}} {
 {{/jdk8-default-interface}}
 {{#operation}}
 
+    /**
+     * {{httpMethod}} {{{path}}}{{#summary}} : {{.}}{{/summary}}
+    {{#notes}}
+     * {{.}}
+    {{/notes}}
+     *
+    {{#allParams}}
+     * @param {{paramName}} {{description}}{{#required}} (required){{/required}}{{^required}} (optional{{#defaultValue}}, default to {{.}}{{/defaultValue}}){{/required}}
+    {{/allParams}}
+     * @return {{#responses}}{{message}} (status code {{code}}){{#hasMore}}
+     *         or {{/hasMore}}{{/responses}}
+    {{#isDeprecated}}
+     * @deprecated
+    {{/isDeprecated}}
+    {{#externalDocs}}
+     * {{description}}
+     * @see <a href="{{url}}">{{summary}} Documentation</a>
+    {{/externalDocs}}
+     */
     {{#virtualService}}
     @ApiVirtual
     {{/virtualService}}

modules/openapi-generator/src/main/resources/JavaSpring/apiController.mustache

@@ -89,6 +89,26 @@ public class {{classname}}Controller implements {{classname}} {
 
 {{^jdk8}}
 {{#operation}}
+    /**
+     * {{httpMethod}} {{{path}}}{{#summary}} : {{.}}{{/summary}}
+    {{#notes}}
+     * {{.}}
+    {{/notes}}
+     *
+    {{#allParams}}
+     * @param {{paramName}} {{description}}{{#required}} (required){{/required}}{{^required}} (optional{{#defaultValue}}, default to {{.}}{{/defaultValue}}){{/required}}
+    {{/allParams}}
+     * @return {{#responses}}{{message}} (status code {{code}}){{#hasMore}}
+     *         or {{/hasMore}}{{/responses}}
+    {{#isDeprecated}}
+     * @deprecated
+    {{/isDeprecated}}
+    {{#externalDocs}}
+     * {{description}}
+     * @see <a href="{{url}}">{{summary}} Documentation</a>
+    {{/externalDocs}}
+     * @see {{classname}}#{{operationId}}
+     */
     public {{#responseWrapper}}{{.}}<{{/responseWrapper}}ResponseEntity<{{>returnTypes}}>{{#responseWrapper}}>{{/responseWrapper}} {{operationId}}({{#allParams}}{{>queryParams}}{{>pathParams}}{{>headerParams}}{{>bodyParams}}{{>formParams}}{{#hasMore}},{{/hasMore}}{{/allParams}}) {
     {{^isDelegate}}
         {{^async}}

modules/openapi-generator/src/main/resources/JavaSpring/apiDelegate.mustache

@@ -48,6 +48,23 @@ public interface {{classname}}Delegate {
 
 {{#operation}}
     /**
+     * {{httpMethod}} {{{path}}}{{#summary}} : {{.}}{{/summary}}
+    {{#notes}}
+     * {{.}}
+    {{/notes}}
+     *
+    {{#allParams}}
+     * @param {{paramName}} {{description}}{{#required}} (required){{/required}}{{^required}} (optional{{#defaultValue}}, default to {{.}}{{/defaultValue}}){{/required}}
+    {{/allParams}}
+     * @return {{#responses}}{{message}} (status code {{code}}){{#hasMore}}
+     *         or {{/hasMore}}{{/responses}}
+    {{#isDeprecated}}
+     * @deprecated
+    {{/isDeprecated}}
+    {{#externalDocs}}
+     * {{description}}
+     * @see <a href="{{url}}">{{summary}} Documentation</a>
+    {{/externalDocs}}
      * @see {{classname}}#{{operationId}}
      */
     {{#jdk8-default-interface}}default {{/jdk8-default-interface}}{{#responseWrapper}}{{.}}<{{/responseWrapper}}ResponseEntity<{{>returnTypes}}>{{#responseWrapper}}>{{/responseWrapper}} {{operationId}}({{#allParams}}{{^isFile}}{{^isBodyParam}}{{>optionalDataType}}{{/isBodyParam}}{{#isBodyParam}}{{^reactive}}{{{dataType}}}{{/reactive}}{{#reactive}}{{^isListContainer}}Mono{{/isListContainer}}{{#isListContainer}}Flux{{/isListContainer}}<{{{baseType}}}>{{/reactive}}{{/isBodyParam}}{{/isFile}}{{#isFile}}MultipartFile{{/isFile}} {{paramName}}{{#hasMore}},

samples/client/petstore/spring-cloud-async/src/main/java/org/openapitools/api/PetApi.java

@@ -34,6 +34,12 @@ import java.util.concurrent.CompletableFuture;
 @Api(value = "Pet", description = "the Pet API")
 public interface PetApi {
 
+    /**
+     * POST /pet : Add a new pet to the store
+     *
+     * @param body Pet object that needs to be added to the store (required)
+     * @return 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"),
@@ -48,6 +54,13 @@ public interface PetApi {
     CompletableFuture<ResponseEntity<Void>> addPet(@ApiParam(value = "Pet object that needs to be added to the store" ,required=true )  @Valid @RequestBody Pet body);
 
 
+    /**
+     * DELETE /pet/{petId} : Deletes a pet
+     *
+     * @param petId Pet id to delete (required)
+     * @param apiKey  (optional)
+     * @return 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"),
@@ -61,6 +74,14 @@ public interface PetApi {
     CompletableFuture<ResponseEntity<Void>> deletePet(@ApiParam(value = "Pet id to delete",required=true) @PathVariable("petId") Long petId,@ApiParam(value = "" ) @RequestHeader(value="api_key", required=false) String apiKey);
 
 
+    /**
+     * 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"),
@@ -76,6 +97,15 @@ public interface PetApi {
     CompletableFuture<ResponseEntity<List<Pet>>> findPetsByStatus(@NotNull @ApiParam(value = "Status values that need to be considered for filter", required = true, allowableValues = "available, pending, sold") @Valid @RequestParam(value = "status", required = true) List<String> status);
 
 
+    /**
+     * 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"),
@@ -91,6 +121,15 @@ public interface PetApi {
     CompletableFuture<ResponseEntity<List<Pet>>> findPetsByTags(@NotNull @ApiParam(value = "Tags to filter by", required = true) @Valid @RequestParam(value = "tags", required = true) List<String> tags);
 
 
+    /**
+     * 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", })
@@ -104,6 +143,14 @@ public interface PetApi {
     CompletableFuture<ResponseEntity<Pet>> getPetById(@ApiParam(value = "ID of pet to return",required=true) @PathVariable("petId") Long petId);
 
 
+    /**
+     * PUT /pet : Update an existing pet
+     *
+     * @param body Pet object that needs to be added to the store (required)
+     * @return 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"),
@@ -120,6 +167,14 @@ public interface PetApi {
     CompletableFuture<ResponseEntity<Void>> updatePet(@ApiParam(value = "Pet object that needs to be added to the store" ,required=true )  @Valid @RequestBody Pet body);
 
 
+    /**
+     * 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"),
@@ -134,6 +189,14 @@ public interface PetApi {
     CompletableFuture<ResponseEntity<Void>> updatePetWithForm(@ApiParam(value = "ID of pet that needs to be updated",required=true) @PathVariable("petId") Long petId,@ApiParam(value = "Updated name of the pet" ) @RequestParam(value="name", required=false)  String name,@ApiParam(value = "Updated status of the pet" ) @RequestParam(value="status", required=false)  String status);
 
 
+    /**
+     * 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/client/petstore/spring-cloud-async/src/main/java/org/openapitools/api/StoreApi.java

@@ -33,6 +33,14 @@ import java.util.concurrent.CompletableFuture;
 @Api(value = "Store", description = "the Store API")
 public interface StoreApi {
 
+    /**
+     * DELETE /store/order/{orderId} : 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"),
@@ -42,6 +50,12 @@ public interface StoreApi {
     CompletableFuture<ResponseEntity<Void>> deleteOrder(@ApiParam(value = "ID of the order that needs to be deleted",required=true) @PathVariable("orderId") String orderId);
 
 
+    /**
+     * 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", })
@@ -53,6 +67,15 @@ public interface StoreApi {
     CompletableFuture<ResponseEntity<Map<String, Integer>>> getInventory();
 
 
+    /**
+     * GET /store/order/{orderId} : 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),
@@ -64,6 +87,13 @@ public interface StoreApi {
     CompletableFuture<ResponseEntity<Order>> getOrderById(@Min(1L) @Max(5L) @ApiParam(value = "ID of pet that needs to be fetched",required=true) @PathVariable("orderId") Long orderId);
 
 
+    /**
+     * 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/client/petstore/spring-cloud-async/src/main/java/org/openapitools/api/UserApi.java

@@ -33,6 +33,13 @@ import java.util.concurrent.CompletableFuture;
 @Api(value = "User", description = "the User API")
 public interface UserApi {
 
+    /**
+     * 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") })
@@ -41,6 +48,12 @@ public interface UserApi {
     CompletableFuture<ResponseEntity<Void>> createUser(@ApiParam(value = "Created user object" ,required=true )  @Valid @RequestBody User body);
 
 
+    /**
+     * 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") })
@@ -49,6 +62,12 @@ public interface UserApi {
     CompletableFuture<ResponseEntity<Void>> createUsersWithArrayInput(@ApiParam(value = "List of user object" ,required=true )  @Valid @RequestBody List<User> body);
 
 
+    /**
+     * 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") })
@@ -57,6 +76,14 @@ public interface UserApi {
     CompletableFuture<ResponseEntity<Void>> createUsersWithListInput(@ApiParam(value = "List of user object" ,required=true )  @Valid @RequestBody List<User> body);
 
 
+    /**
+     * 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"),
@@ -66,6 +93,14 @@ public interface UserApi {
     CompletableFuture<ResponseEntity<Void>> deleteUser(@ApiParam(value = "The name that needs to be deleted",required=true) @PathVariable("username") String username);
 
 
+    /**
+     * 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),
@@ -77,6 +112,14 @@ public interface UserApi {
     CompletableFuture<ResponseEntity<User>> getUserByName(@ApiParam(value = "The name that needs to be fetched. Use user1 for testing.",required=true) @PathVariable("username") String username);
 
 
+    /**
+     * 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),
@@ -87,6 +130,11 @@ public interface UserApi {
     CompletableFuture<ResponseEntity<String>> loginUser(@NotNull @ApiParam(value = "The user name for login", required = true) @Valid @RequestParam(value = "username", required = true) String username,@NotNull @ApiParam(value = "The password for login in clear text", required = true) @Valid @RequestParam(value = "password", required = true) String password);
 
 
+    /**
+     * 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") })
@@ -95,6 +143,15 @@ public interface UserApi {
     CompletableFuture<ResponseEntity<Void>> logoutUser();
 
 
+    /**
+     * 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"),

samples/client/petstore/spring-cloud/src/main/java/org/openapitools/api/PetApi.java

@@ -33,6 +33,12 @@ import java.util.Optional;
 @Api(value = "Pet", description = "the Pet API")
 public interface PetApi {
 
+    /**
+     * POST /pet : Add a new pet to the store
+     *
+     * @param body Pet object that needs to be added to the store (required)
+     * @return 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"),
@@ -47,6 +53,13 @@ public interface PetApi {
     com.netflix.hystrix.HystrixCommand<ResponseEntity<Void>> addPet(@ApiParam(value = "Pet object that needs to be added to the store" ,required=true )  @Valid @RequestBody Pet body);
 
 
+    /**
+     * DELETE /pet/{petId} : Deletes a pet
+     *
+     * @param petId Pet id to delete (required)
+     * @param apiKey  (optional)
+     * @return 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"),
@@ -60,6 +73,14 @@ public interface PetApi {
     com.netflix.hystrix.HystrixCommand<ResponseEntity<Void>> deletePet(@ApiParam(value = "Pet id to delete",required=true) @PathVariable("petId") Long petId,@ApiParam(value = "" ) @RequestHeader(value="api_key", required=false) String apiKey);
 
 
+    /**
+     * 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"),
@@ -75,6 +96,15 @@ public interface PetApi {
     com.netflix.hystrix.HystrixCommand<ResponseEntity<List<Pet>>> findPetsByStatus(@NotNull @ApiParam(value = "Status values that need to be considered for filter", required = true, allowableValues = "available, pending, sold") @Valid @RequestParam(value = "status", required = true) List<String> status);
 
 
+    /**
+     * 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"),
@@ -90,6 +120,15 @@ public interface PetApi {
     com.netflix.hystrix.HystrixCommand<ResponseEntity<List<Pet>>> findPetsByTags(@NotNull @ApiParam(value = "Tags to filter by", required = true) @Valid @RequestParam(value = "tags", required = true) List<String> tags);
 
 
+    /**
+     * 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", })
@@ -103,6 +142,14 @@ public interface PetApi {
     com.netflix.hystrix.HystrixCommand<ResponseEntity<Pet>> getPetById(@ApiParam(value = "ID of pet to return",required=true) @PathVariable("petId") Long petId);
 
 
+    /**
+     * PUT /pet : Update an existing pet
+     *
+     * @param body Pet object that needs to be added to the store (required)
+     * @return 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"),
@@ -119,6 +166,14 @@ public interface PetApi {
     com.netflix.hystrix.HystrixCommand<ResponseEntity<Void>> updatePet(@ApiParam(value = "Pet object that needs to be added to the store" ,required=true )  @Valid @RequestBody Pet body);
 
 
+    /**
+     * 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"),
@@ -133,6 +188,14 @@ public interface PetApi {
     com.netflix.hystrix.HystrixCommand<ResponseEntity<Void>> updatePetWithForm(@ApiParam(value = "ID of pet that needs to be updated",required=true) @PathVariable("petId") Long petId,@ApiParam(value = "Updated name of the pet" ) @RequestParam(value="name", required=false)  String name,@ApiParam(value = "Updated status of the pet" ) @RequestParam(value="status", required=false)  String status);
 
 
+    /**
+     * 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/client/petstore/spring-cloud/src/main/java/org/openapitools/api/StoreApi.java

@@ -32,6 +32,14 @@ import java.util.Optional;
 @Api(value = "Store", description = "the Store API")
 public interface StoreApi {
 
+    /**
+     * DELETE /store/order/{orderId} : 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"),
@@ -41,6 +49,12 @@ public interface StoreApi {
     com.netflix.hystrix.HystrixCommand<ResponseEntity<Void>> deleteOrder(@ApiParam(value = "ID of the order that needs to be deleted",required=true) @PathVariable("orderId") String orderId);
 
 
+    /**
+     * 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", })
@@ -52,6 +66,15 @@ public interface StoreApi {
     com.netflix.hystrix.HystrixCommand<ResponseEntity<Map<String, Integer>>> getInventory();
 
 
+    /**
+     * GET /store/order/{orderId} : 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),
@@ -63,6 +86,13 @@ public interface StoreApi {
     com.netflix.hystrix.HystrixCommand<ResponseEntity<Order>> getOrderById(@Min(1L) @Max(5L) @ApiParam(value = "ID of pet that needs to be fetched",required=true) @PathVariable("orderId") Long orderId);
 
 
+    /**
+     * 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/client/petstore/spring-cloud/src/main/java/org/openapitools/api/UserApi.java

@@ -32,6 +32,13 @@ import java.util.Optional;
 @Api(value = "User", description = "the User API")
 public interface UserApi {
 
+    /**
+     * 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") })
@@ -40,6 +47,12 @@ public interface UserApi {
     com.netflix.hystrix.HystrixCommand<ResponseEntity<Void>> createUser(@ApiParam(value = "Created user object" ,required=true )  @Valid @RequestBody User body);
 
 
+    /**
+     * 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") })
@@ -48,6 +61,12 @@ public interface UserApi {
     com.netflix.hystrix.HystrixCommand<ResponseEntity<Void>> createUsersWithArrayInput(@ApiParam(value = "List of user object" ,required=true )  @Valid @RequestBody List<User> body);
 
 
+    /**
+     * 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") })
@@ -56,6 +75,14 @@ public interface UserApi {
     com.netflix.hystrix.HystrixCommand<ResponseEntity<Void>> createUsersWithListInput(@ApiParam(value = "List of user object" ,required=true )  @Valid @RequestBody List<User> body);
 
 
+    /**
+     * 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"),
@@ -65,6 +92,14 @@ public interface UserApi {
     com.netflix.hystrix.HystrixCommand<ResponseEntity<Void>> deleteUser(@ApiParam(value = "The name that needs to be deleted",required=true) @PathVariable("username") String username);
 
 
+    /**
+     * 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),
@@ -76,6 +111,14 @@ public interface UserApi {
     com.netflix.hystrix.HystrixCommand<ResponseEntity<User>> getUserByName(@ApiParam(value = "The name that needs to be fetched. Use user1 for testing.",required=true) @PathVariable("username") String username);
 
 
+    /**
+     * 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),
@@ -86,6 +129,11 @@ public interface UserApi {
     com.netflix.hystrix.HystrixCommand<ResponseEntity<String>> loginUser(@NotNull @ApiParam(value = "The user name for login", required = true) @Valid @RequestParam(value = "username", required = true) String username,@NotNull @ApiParam(value = "The password for login in clear text", required = true) @Valid @RequestParam(value = "password", required = true) String password);
 
 
+    /**
+     * 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") })
@@ -94,6 +142,15 @@ public interface UserApi {
     com.netflix.hystrix.HystrixCommand<ResponseEntity<Void>> logoutUser();
 
 
+    /**
+     * 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"),

samples/client/petstore/spring-stubs/src/main/java/org/openapitools/api/PetApi.java

@@ -37,6 +37,12 @@ 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 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"),
@@ -54,6 +60,13 @@ public interface PetApi {
     }
 
 
+    /**
+     * DELETE /pet/{petId} : Deletes a pet
+     *
+     * @param petId Pet id to delete (required)
+     * @param apiKey  (optional)
+     * @return 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"),
@@ -70,6 +83,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"),
@@ -102,6 +123,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"),
@@ -134,6 +164,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", })
@@ -164,6 +203,14 @@ public interface PetApi {
     }
 
 
+    /**
+     * PUT /pet : Update an existing pet
+     *
+     * @param body Pet object that needs to be added to the store (required)
+     * @return 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"),
@@ -183,6 +230,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"),
@@ -200,6 +255,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/client/petstore/spring-stubs/src/main/java/org/openapitools/api/StoreApi.java

@@ -36,6 +36,14 @@ public interface StoreApi {
         return Optional.empty();
     }
 
+    /**
+     * DELETE /store/order/{orderId} : 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"),
@@ -48,6 +56,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", })
@@ -62,6 +76,15 @@ public interface StoreApi {
     }
 
 
+    /**
+     * GET /store/order/{orderId} : 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),
@@ -90,6 +113,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/client/petstore/spring-stubs/src/main/java/org/openapitools/api/UserApi.java

@@ -36,6 +36,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") })
@@ -47,6 +54,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") })
@@ -58,6 +71,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") })
@@ -69,6 +88,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"),
@@ -81,6 +108,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),
@@ -109,6 +144,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),
@@ -122,6 +165,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") })
@@ -133,6 +181,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"),

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"),

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

@@ -35,6 +35,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-localdatetime/src/main/java/org/openapitools/api/FakeApi.java

@@ -45,6 +45,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") })
@@ -57,6 +64,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) })
@@ -69,6 +83,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) })
@@ -90,6 +111,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) })
@@ -102,6 +130,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) })
@@ -114,6 +149,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") })
@@ -126,6 +168,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") })
@@ -138,6 +187,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) })
@@ -160,6 +216,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", })
@@ -175,6 +252,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"),
@@ -188,6 +280,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") })
@@ -199,6 +303,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") })
@@ -211,6 +321,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") })
@@ -223,6 +340,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") })
@@ -234,6 +362,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-localdatetime/src/main/java/org/openapitools/api/FakeClassnameTestApi.java

@@ -35,6 +35,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-localdatetime/src/main/java/org/openapitools/api/PetApi.java

@@ -37,6 +37,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"),
@@ -55,6 +62,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"),
@@ -72,6 +87,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"),
@@ -104,6 +127,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"),
@@ -136,6 +168,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", })
@@ -166,6 +207,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"),
@@ -186,6 +236,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"),
@@ -203,6 +261,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-localdatetime/src/main/java/org/openapitools/api/StoreApi.java

@@ -36,6 +36,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"),
@@ -48,6 +56,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", })
@@ -62,6 +76,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),
@@ -90,6 +113,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-localdatetime/src/main/java/org/openapitools/api/UserApi.java

@@ -36,6 +36,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") })
@@ -47,6 +54,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") })
@@ -58,6 +71,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") })
@@ -69,6 +88,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"),
@@ -81,6 +108,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),
@@ -109,6 +144,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),
@@ -122,6 +165,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") })
@@ -133,6 +181,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"),

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

@@ -27,6 +27,13 @@ import java.util.Map;
 @Api(value = "another-fake", description = "the another-fake API")
 public interface AnotherFakeApi {
 
+    /**
+     * 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/src/main/java/org/openapitools/api/AnotherFakeApiController.java

@@ -31,6 +31,14 @@ public class AnotherFakeApiController implements AnotherFakeApi {
         this.request = request;
     }
 
+    /**
+     * 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)
+     * @see AnotherFakeApi#call123testSpecialTags
+     */
     public ResponseEntity<Client> call123testSpecialTags(@ApiParam(value = "client model" ,required=true )  @Valid @RequestBody Client body) {
         for (MediaType mediaType: MediaType.parseMediaTypes(request.getHeader("Accept"))) {
             if (mediaType.isCompatibleWith(MediaType.valueOf("application/json"))) {

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

@@ -37,6 +37,13 @@ import java.util.Map;
 @Api(value = "fake", description = "the fake API")
 public interface FakeApi {
 
+    /**
+     * 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") })
@@ -46,6 +53,13 @@ public interface FakeApi {
     ResponseEntity<Void> createXmlItem(@ApiParam(value = "XmlItem Body" ,required=true )  @Valid @RequestBody XmlItem xmlItem);
 
 
+    /**
+     * 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) })
@@ -55,6 +69,13 @@ public interface FakeApi {
     ResponseEntity<Boolean> fakeOuterBooleanSerialize(@ApiParam(value = "Input boolean as post body"  )  @Valid @RequestBody Boolean body);
 
 
+    /**
+     * 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) })
@@ -64,6 +85,13 @@ public interface FakeApi {
     ResponseEntity<OuterComposite> fakeOuterCompositeSerialize(@ApiParam(value = "Input composite as post body"  )  @Valid @RequestBody OuterComposite body);
 
 
+    /**
+     * 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) })
@@ -73,6 +101,13 @@ public interface FakeApi {
     ResponseEntity<BigDecimal> fakeOuterNumberSerialize(@ApiParam(value = "Input number as post body"  )  @Valid @RequestBody BigDecimal body);
 
 
+    /**
+     * 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) })
@@ -82,6 +117,13 @@ public interface FakeApi {
     ResponseEntity<String> fakeOuterStringSerialize(@ApiParam(value = "Input string as post body"  )  @Valid @RequestBody String body);
 
 
+    /**
+     * PUT /fake/body-with-file-schema
+     * For this test, the body for this request much reference a schema named &#x60;File&#x60;.
+     *
+     * @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") })
@@ -91,6 +133,13 @@ public interface FakeApi {
     ResponseEntity<Void> testBodyWithFileSchema(@ApiParam(value = "" ,required=true )  @Valid @RequestBody FileSchemaTestClass body);
 
 
+    /**
+     * 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") })
@@ -100,6 +149,13 @@ public interface FakeApi {
     ResponseEntity<Void> testBodyWithQueryParams(@NotNull @ApiParam(value = "", required = true) @Valid @RequestParam(value = "query", required = true) String query,@ApiParam(value = "" ,required=true )  @Valid @RequestBody User body);
 
 
+    /**
+     * PATCH /fake : To test \&quot;client\&quot; model
+     * To test \&quot;client\&quot; 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) })
@@ -110,6 +166,27 @@ public interface FakeApi {
     ResponseEntity<Client> testClientModel(@ApiParam(value = "client model" ,required=true )  @Valid @RequestBody Client body);
 
 
+    /**
+     * 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", })
@@ -122,6 +199,21 @@ public interface FakeApi {
     ResponseEntity<Void> testEndpointParameters(@ApiParam(value = "None", required=true) @RequestParam(value="number", required=true)  BigDecimal number,@ApiParam(value = "None", required=true) @RequestParam(value="double", required=true)  Double _double,@ApiParam(value = "None", required=true) @RequestParam(value="pattern_without_delimiter", required=true)  String patternWithoutDelimiter,@ApiParam(value = "None", required=true) @RequestParam(value="byte", required=true)  byte[] _byte,@ApiParam(value = "None") @RequestParam(value="integer", required=false)  Integer integer,@ApiParam(value = "None") @RequestParam(value="int32", required=false)  Integer int32,@ApiParam(value = "None") @RequestParam(value="int64", required=false)  Long int64,@ApiParam(value = "None") @RequestParam(value="float", required=false)  Float _float,@ApiParam(value = "None") @RequestParam(value="string", required=false)  String string,@ApiParam(value = "file detail") @Valid @RequestPart("file") MultipartFile binary,@ApiParam(value = "None") @RequestParam(value="date", required=false)  LocalDate date,@ApiParam(value = "None") @RequestParam(value="dateTime", required=false)  OffsetDateTime dateTime,@ApiParam(value = "None") @RequestParam(value="password", required=false)  String password,@ApiParam(value = "None") @RequestParam(value="callback", required=false)  String paramCallback);
 
 
+    /**
+     * GET /fake : To test enum parameters
+     * To test enum parameters
+     *
+     * @param enumHeaderStringArray Header parameter enum test (string array) (optional, default to new ArrayList&lt;String&gt;())
+     * @param enumHeaderString Header parameter enum test (string) (optional, default to -efg)
+     * @param enumQueryStringArray Query parameter enum test (string array) (optional, default to new ArrayList&lt;String&gt;())
+     * @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"),
@@ -132,6 +224,18 @@ public interface FakeApi {
     ResponseEntity<Void> testEnumParameters(@ApiParam(value = "Header parameter enum test (string array)" , allowableValues=">, $") @RequestHeader(value="enum_header_string_array", required=false) List<String> enumHeaderStringArray,@ApiParam(value = "Header parameter enum test (string)" , allowableValues="_abc, -efg, (xyz)", defaultValue="-efg") @RequestHeader(value="enum_header_string", required=false) String enumHeaderString,@ApiParam(value = "Query parameter enum test (string array)", allowableValues = ">, $") @Valid @RequestParam(value = "enum_query_string_array", required = false) List<String> enumQueryStringArray,@ApiParam(value = "Query parameter enum test (string)", allowableValues = "_abc, -efg, (xyz)", defaultValue = "-efg") @Valid @RequestParam(value = "enum_query_string", required = false, defaultValue="-efg") String enumQueryString,@ApiParam(value = "Query parameter enum test (double)", allowableValues = "1, -2") @Valid @RequestParam(value = "enum_query_integer", required = false) Integer enumQueryInteger,@ApiParam(value = "Query parameter enum test (double)", allowableValues = "1.1, -1.2") @Valid @RequestParam(value = "enum_query_double", required = false) Double enumQueryDouble,@ApiParam(value = "Form parameter enum test (string array)", allowableValues=">, $") @RequestParam(value="enum_form_string_array", required=false)  List<String> enumFormStringArray,@ApiParam(value = "Form parameter enum test (string)", allowableValues="_abc, -efg, (xyz)", defaultValue="-efg") @RequestParam(value="enum_form_string", required=false)  String enumFormString);
 
 
+    /**
+     * 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") })
@@ -140,6 +244,12 @@ public interface FakeApi {
     ResponseEntity<Void> testGroupParameters(@NotNull @ApiParam(value = "Required String in group parameters", required = true) @Valid @RequestParam(value = "required_string_group", required = true) Integer requiredStringGroup,@ApiParam(value = "Required Boolean in group parameters" ,required=true) @RequestHeader(value="required_boolean_group", required=true) Boolean requiredBooleanGroup,@NotNull @ApiParam(value = "Required Integer in group parameters", required = true) @Valid @RequestParam(value = "required_int64_group", required = true) Long requiredInt64Group,@ApiParam(value = "String in group parameters") @Valid @RequestParam(value = "string_group", required = false) Integer stringGroup,@ApiParam(value = "Boolean in group parameters" ) @RequestHeader(value="boolean_group", required=false) Boolean booleanGroup,@ApiParam(value = "Integer in group parameters") @Valid @RequestParam(value = "int64_group", required = false) Long int64Group);
 
 
+    /**
+     * 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") })
@@ -149,6 +259,13 @@ public interface FakeApi {
     ResponseEntity<Void> testInlineAdditionalProperties(@ApiParam(value = "request body" ,required=true )  @Valid @RequestBody Map<String, String> param);
 
 
+    /**
+     * 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") })
@@ -158,6 +275,17 @@ public interface FakeApi {
     ResponseEntity<Void> testJsonFormData(@ApiParam(value = "field1", required=true) @RequestParam(value="param", required=true)  String param,@ApiParam(value = "field2", required=true) @RequestParam(value="param2", required=true)  String param2);
 
 
+    /**
+     * 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") })
@@ -166,6 +294,14 @@ public interface FakeApi {
     ResponseEntity<Void> testQueryParameterCollectionFormat(@NotNull @ApiParam(value = "", required = true) @Valid @RequestParam(value = "pipe", required = true) List<String> pipe,@NotNull @ApiParam(value = "", required = true) @Valid @RequestParam(value = "ioutil", required = true) List<String> ioutil,@NotNull @ApiParam(value = "", required = true) @Valid @RequestParam(value = "http", required = true) List<String> http,@NotNull @ApiParam(value = "", required = true) @Valid @RequestParam(value = "url", required = true) List<String> url,@NotNull @ApiParam(value = "", required = true) @Valid @RequestParam(value = "context", required = true) List<String> context);
 
 
+    /**
+     * 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/src/main/java/org/openapitools/api/FakeApiController.java

@@ -41,16 +41,40 @@ public class FakeApiController implements FakeApi {
         this.request = request;
     }
 
+    /**
+     * POST /fake/create_xml_item : creates an XmlItem
+     * this route creates an XmlItem
+     *
+     * @param xmlItem XmlItem Body (required)
+     * @return successful operation (status code 200)
+     * @see FakeApi#createXmlItem
+     */
     public ResponseEntity<Void> createXmlItem(@ApiParam(value = "XmlItem Body" ,required=true )  @Valid @RequestBody XmlItem xmlItem) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * POST /fake/outer/boolean
+     * Test serialization of outer boolean types
+     *
+     * @param body Input boolean as post body (optional)
+     * @return Output boolean (status code 200)
+     * @see FakeApi#fakeOuterBooleanSerialize
+     */
     public ResponseEntity<Boolean> fakeOuterBooleanSerialize(@ApiParam(value = "Input boolean as post body"  )  @Valid @RequestBody Boolean body) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * 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)
+     * @see FakeApi#fakeOuterCompositeSerialize
+     */
     public ResponseEntity<OuterComposite> fakeOuterCompositeSerialize(@ApiParam(value = "Input composite as post body"  )  @Valid @RequestBody OuterComposite body) {
         for (MediaType mediaType: MediaType.parseMediaTypes(request.getHeader("Accept"))) {
             if (mediaType.isCompatibleWith(MediaType.valueOf("*/*"))) {
@@ -63,26 +87,66 @@ public class FakeApiController implements 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)
+     * @see FakeApi#fakeOuterNumberSerialize
+     */
     public ResponseEntity<BigDecimal> fakeOuterNumberSerialize(@ApiParam(value = "Input number as post body"  )  @Valid @RequestBody BigDecimal body) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * POST /fake/outer/string
+     * Test serialization of outer string types
+     *
+     * @param body Input string as post body (optional)
+     * @return Output string (status code 200)
+     * @see FakeApi#fakeOuterStringSerialize
+     */
     public ResponseEntity<String> fakeOuterStringSerialize(@ApiParam(value = "Input string as post body"  )  @Valid @RequestBody String body) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * PUT /fake/body-with-file-schema
+     * For this test, the body for this request much reference a schema named &#x60;File&#x60;.
+     *
+     * @param body  (required)
+     * @return Success (status code 200)
+     * @see FakeApi#testBodyWithFileSchema
+     */
     public ResponseEntity<Void> testBodyWithFileSchema(@ApiParam(value = "" ,required=true )  @Valid @RequestBody FileSchemaTestClass body) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * PUT /fake/body-with-query-params
+     *
+     * @param query  (required)
+     * @param body  (required)
+     * @return Success (status code 200)
+     * @see FakeApi#testBodyWithQueryParams
+     */
     public ResponseEntity<Void> testBodyWithQueryParams(@NotNull @ApiParam(value = "", required = true) @Valid @RequestParam(value = "query", required = true) String query,@ApiParam(value = "" ,required=true )  @Valid @RequestBody User body) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * PATCH /fake : To test \&quot;client\&quot; model
+     * To test \&quot;client\&quot; model
+     *
+     * @param body client model (required)
+     * @return successful operation (status code 200)
+     * @see FakeApi#testClientModel
+     */
     public ResponseEntity<Client> testClientModel(@ApiParam(value = "client model" ,required=true )  @Valid @RequestBody Client body) {
         for (MediaType mediaType: MediaType.parseMediaTypes(request.getHeader("Accept"))) {
             if (mediaType.isCompatibleWith(MediaType.valueOf("application/json"))) {
@@ -95,36 +159,123 @@ public class FakeApiController implements 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)
+     * @see FakeApi#testEndpointParameters
+     */
     public ResponseEntity<Void> testEndpointParameters(@ApiParam(value = "None", required=true) @RequestParam(value="number", required=true)  BigDecimal number,@ApiParam(value = "None", required=true) @RequestParam(value="double", required=true)  Double _double,@ApiParam(value = "None", required=true) @RequestParam(value="pattern_without_delimiter", required=true)  String patternWithoutDelimiter,@ApiParam(value = "None", required=true) @RequestParam(value="byte", required=true)  byte[] _byte,@ApiParam(value = "None") @RequestParam(value="integer", required=false)  Integer integer,@ApiParam(value = "None") @RequestParam(value="int32", required=false)  Integer int32,@ApiParam(value = "None") @RequestParam(value="int64", required=false)  Long int64,@ApiParam(value = "None") @RequestParam(value="float", required=false)  Float _float,@ApiParam(value = "None") @RequestParam(value="string", required=false)  String string,@ApiParam(value = "file detail") @Valid @RequestPart("file") MultipartFile binary,@ApiParam(value = "None") @RequestParam(value="date", required=false)  LocalDate date,@ApiParam(value = "None") @RequestParam(value="dateTime", required=false)  OffsetDateTime dateTime,@ApiParam(value = "None") @RequestParam(value="password", required=false)  String password,@ApiParam(value = "None") @RequestParam(value="callback", required=false)  String paramCallback) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * GET /fake : To test enum parameters
+     * To test enum parameters
+     *
+     * @param enumHeaderStringArray Header parameter enum test (string array) (optional, default to new ArrayList&lt;String&gt;())
+     * @param enumHeaderString Header parameter enum test (string) (optional, default to -efg)
+     * @param enumQueryStringArray Query parameter enum test (string array) (optional, default to new ArrayList&lt;String&gt;())
+     * @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)
+     * @see FakeApi#testEnumParameters
+     */
     public ResponseEntity<Void> testEnumParameters(@ApiParam(value = "Header parameter enum test (string array)" , allowableValues=">, $") @RequestHeader(value="enum_header_string_array", required=false) List<String> enumHeaderStringArray,@ApiParam(value = "Header parameter enum test (string)" , allowableValues="_abc, -efg, (xyz)", defaultValue="-efg") @RequestHeader(value="enum_header_string", required=false) String enumHeaderString,@ApiParam(value = "Query parameter enum test (string array)", allowableValues = ">, $") @Valid @RequestParam(value = "enum_query_string_array", required = false) List<String> enumQueryStringArray,@ApiParam(value = "Query parameter enum test (string)", allowableValues = "_abc, -efg, (xyz)", defaultValue = "-efg") @Valid @RequestParam(value = "enum_query_string", required = false, defaultValue="-efg") String enumQueryString,@ApiParam(value = "Query parameter enum test (double)", allowableValues = "1, -2") @Valid @RequestParam(value = "enum_query_integer", required = false) Integer enumQueryInteger,@ApiParam(value = "Query parameter enum test (double)", allowableValues = "1.1, -1.2") @Valid @RequestParam(value = "enum_query_double", required = false) Double enumQueryDouble,@ApiParam(value = "Form parameter enum test (string array)", allowableValues=">, $") @RequestParam(value="enum_form_string_array", required=false)  List<String> enumFormStringArray,@ApiParam(value = "Form parameter enum test (string)", allowableValues="_abc, -efg, (xyz)", defaultValue="-efg") @RequestParam(value="enum_form_string", required=false)  String enumFormString) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * 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)
+     * @see FakeApi#testGroupParameters
+     */
     public ResponseEntity<Void> testGroupParameters(@NotNull @ApiParam(value = "Required String in group parameters", required = true) @Valid @RequestParam(value = "required_string_group", required = true) Integer requiredStringGroup,@ApiParam(value = "Required Boolean in group parameters" ,required=true) @RequestHeader(value="required_boolean_group", required=true) Boolean requiredBooleanGroup,@NotNull @ApiParam(value = "Required Integer in group parameters", required = true) @Valid @RequestParam(value = "required_int64_group", required = true) Long requiredInt64Group,@ApiParam(value = "String in group parameters") @Valid @RequestParam(value = "string_group", required = false) Integer stringGroup,@ApiParam(value = "Boolean in group parameters" ) @RequestHeader(value="boolean_group", required=false) Boolean booleanGroup,@ApiParam(value = "Integer in group parameters") @Valid @RequestParam(value = "int64_group", required = false) Long int64Group) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * POST /fake/inline-additionalProperties : test inline additionalProperties
+     *
+     * @param param request body (required)
+     * @return successful operation (status code 200)
+     * @see FakeApi#testInlineAdditionalProperties
+     */
     public ResponseEntity<Void> testInlineAdditionalProperties(@ApiParam(value = "request body" ,required=true )  @Valid @RequestBody Map<String, String> param) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * GET /fake/jsonFormData : test json serialization of form data
+     *
+     * @param param field1 (required)
+     * @param param2 field2 (required)
+     * @return successful operation (status code 200)
+     * @see FakeApi#testJsonFormData
+     */
     public ResponseEntity<Void> testJsonFormData(@ApiParam(value = "field1", required=true) @RequestParam(value="param", required=true)  String param,@ApiParam(value = "field2", required=true) @RequestParam(value="param2", required=true)  String param2) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * 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)
+     * @see FakeApi#testQueryParameterCollectionFormat
+     */
     public ResponseEntity<Void> testQueryParameterCollectionFormat(@NotNull @ApiParam(value = "", required = true) @Valid @RequestParam(value = "pipe", required = true) List<String> pipe,@NotNull @ApiParam(value = "", required = true) @Valid @RequestParam(value = "ioutil", required = true) List<String> ioutil,@NotNull @ApiParam(value = "", required = true) @Valid @RequestParam(value = "http", required = true) List<String> http,@NotNull @ApiParam(value = "", required = true) @Valid @RequestParam(value = "url", required = true) List<String> url,@NotNull @ApiParam(value = "", required = true) @Valid @RequestParam(value = "context", required = true) List<String> context) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * 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)
+     * @see FakeApi#uploadFileWithRequiredFile
+     */
     public ResponseEntity<ModelApiResponse> uploadFileWithRequiredFile(@ApiParam(value = "ID of pet to update",required=true) @PathVariable("petId") Long petId,@ApiParam(value = "file detail") @Valid @RequestPart("file") MultipartFile requiredFile,@ApiParam(value = "Additional data to pass to server") @RequestParam(value="additionalMetadata", required=false)  String additionalMetadata) {
         for (MediaType mediaType: MediaType.parseMediaTypes(request.getHeader("Accept"))) {
             if (mediaType.isCompatibleWith(MediaType.valueOf("application/json"))) {

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

@@ -27,6 +27,13 @@ import java.util.Map;
 @Api(value = "fake_classname_test", description = "the fake_classname_test API")
 public interface FakeClassnameTestApi {
 
+    /**
+     * 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/src/main/java/org/openapitools/api/FakeClassnameTestApiController.java

@@ -31,6 +31,14 @@ public class FakeClassnameTestApiController implements FakeClassnameTestApi {
         this.request = request;
     }
 
+    /**
+     * 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)
+     * @see FakeClassnameTestApi#testClassname
+     */
     public ResponseEntity<Client> testClassname(@ApiParam(value = "client model" ,required=true )  @Valid @RequestBody Client body) {
         for (MediaType mediaType: MediaType.parseMediaTypes(request.getHeader("Accept"))) {
             if (mediaType.isCompatibleWith(MediaType.valueOf("application/json"))) {

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

@@ -29,6 +29,13 @@ import java.util.Map;
 @Api(value = "pet", description = "the pet API")
 public interface PetApi {
 
+    /**
+     * 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"),
@@ -44,6 +51,14 @@ public interface PetApi {
     ResponseEntity<Void> addPet(@ApiParam(value = "Pet object that needs to be added to the store" ,required=true )  @Valid @RequestBody Pet body);
 
 
+    /**
+     * 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"),
@@ -58,6 +73,14 @@ public interface PetApi {
     ResponseEntity<Void> deletePet(@ApiParam(value = "Pet id to delete",required=true) @PathVariable("petId") Long petId,@ApiParam(value = "" ) @RequestHeader(value="api_key", required=false) String apiKey);
 
 
+    /**
+     * 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"),
@@ -73,6 +96,15 @@ public interface PetApi {
     ResponseEntity<List<Pet>> findPetsByStatus(@NotNull @ApiParam(value = "Status values that need to be considered for filter", required = true, allowableValues = "available, pending, sold") @Valid @RequestParam(value = "status", required = true) List<String> status);
 
 
+    /**
+     * 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"),
@@ -88,6 +120,15 @@ public interface PetApi {
     ResponseEntity<List<Pet>> findPetsByTags(@NotNull @ApiParam(value = "Tags to filter by", required = true) @Valid @RequestParam(value = "tags", required = true) List<String> tags);
 
 
+    /**
+     * 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", })
@@ -101,6 +142,15 @@ public interface PetApi {
     ResponseEntity<Pet> getPetById(@ApiParam(value = "ID of pet to return",required=true) @PathVariable("petId") Long petId);
 
 
+    /**
+     * 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"),
@@ -118,6 +168,14 @@ public interface PetApi {
     ResponseEntity<Void> updatePet(@ApiParam(value = "Pet object that needs to be added to the store" ,required=true )  @Valid @RequestBody Pet body);
 
 
+    /**
+     * 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"),
@@ -132,6 +190,14 @@ public interface PetApi {
     ResponseEntity<Void> updatePetWithForm(@ApiParam(value = "ID of pet that needs to be updated",required=true) @PathVariable("petId") Long petId,@ApiParam(value = "Updated name of the pet") @RequestParam(value="name", required=false)  String name,@ApiParam(value = "Updated status of the pet") @RequestParam(value="status", required=false)  String status);
 
 
+    /**
+     * 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/src/main/java/org/openapitools/api/PetApiController.java

@@ -33,16 +33,42 @@ public class PetApiController implements PetApi {
         this.request = request;
     }
 
+    /**
+     * 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)
+     * @see PetApi#addPet
+     */
     public ResponseEntity<Void> addPet(@ApiParam(value = "Pet object that needs to be added to the store" ,required=true )  @Valid @RequestBody Pet body) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * 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)
+     * @see PetApi#deletePet
+     */
     public ResponseEntity<Void> deletePet(@ApiParam(value = "Pet id to delete",required=true) @PathVariable("petId") Long petId,@ApiParam(value = "" ) @RequestHeader(value="api_key", required=false) String apiKey) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * 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)
+     * @see PetApi#findPetsByStatus
+     */
     public ResponseEntity<List<Pet>> findPetsByStatus(@NotNull @ApiParam(value = "Status values that need to be considered for filter", required = true, allowableValues = "available, pending, sold") @Valid @RequestParam(value = "status", required = true) List<String> status) {
         for (MediaType mediaType: MediaType.parseMediaTypes(request.getHeader("Accept"))) {
             if (mediaType.isCompatibleWith(MediaType.valueOf("application/json"))) {
@@ -60,6 +86,16 @@ public class PetApiController implements 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
+     * @see PetApi#findPetsByTags
+     */
     public ResponseEntity<List<Pet>> findPetsByTags(@NotNull @ApiParam(value = "Tags to filter by", required = true) @Valid @RequestParam(value = "tags", required = true) List<String> tags) {
         for (MediaType mediaType: MediaType.parseMediaTypes(request.getHeader("Accept"))) {
             if (mediaType.isCompatibleWith(MediaType.valueOf("application/json"))) {
@@ -77,6 +113,16 @@ public class PetApiController implements 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)
+     * @see PetApi#getPetById
+     */
     public ResponseEntity<Pet> getPetById(@ApiParam(value = "ID of pet to return",required=true) @PathVariable("petId") Long petId) {
         for (MediaType mediaType: MediaType.parseMediaTypes(request.getHeader("Accept"))) {
             if (mediaType.isCompatibleWith(MediaType.valueOf("application/json"))) {
@@ -94,16 +140,44 @@ public class PetApiController implements 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)
+     * @see PetApi#updatePet
+     */
     public ResponseEntity<Void> updatePet(@ApiParam(value = "Pet object that needs to be added to the store" ,required=true )  @Valid @RequestBody Pet body) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * 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)
+     * @see PetApi#updatePetWithForm
+     */
     public ResponseEntity<Void> updatePetWithForm(@ApiParam(value = "ID of pet that needs to be updated",required=true) @PathVariable("petId") Long petId,@ApiParam(value = "Updated name of the pet") @RequestParam(value="name", required=false)  String name,@ApiParam(value = "Updated status of the pet") @RequestParam(value="status", required=false)  String status) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * 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)
+     * @see PetApi#uploadFile
+     */
     public ResponseEntity<ModelApiResponse> uploadFile(@ApiParam(value = "ID of pet to update",required=true) @PathVariable("petId") Long petId,@ApiParam(value = "Additional data to pass to server") @RequestParam(value="additionalMetadata", required=false)  String additionalMetadata,@ApiParam(value = "file detail") @Valid @RequestPart("file") MultipartFile file) {
         for (MediaType mediaType: MediaType.parseMediaTypes(request.getHeader("Accept"))) {
             if (mediaType.isCompatibleWith(MediaType.valueOf("application/json"))) {

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

@@ -28,6 +28,14 @@ import java.util.Map;
 @Api(value = "store", description = "the store API")
 public interface StoreApi {
 
+    /**
+     * 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"),
@@ -37,6 +45,12 @@ public interface StoreApi {
     ResponseEntity<Void> deleteOrder(@ApiParam(value = "ID of the order that needs to be deleted",required=true) @PathVariable("order_id") String orderId);
 
 
+    /**
+     * 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", })
@@ -48,6 +62,15 @@ public interface StoreApi {
     ResponseEntity<Map<String, Integer>> getInventory();
 
 
+    /**
+     * 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),
@@ -59,6 +82,13 @@ public interface StoreApi {
     ResponseEntity<Order> getOrderById(@Min(1L) @Max(5L) @ApiParam(value = "ID of pet that needs to be fetched",required=true) @PathVariable("order_id") Long orderId);
 
 
+    /**
+     * 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/src/main/java/org/openapitools/api/StoreApiController.java

@@ -32,16 +32,42 @@ public class StoreApiController implements StoreApi {
         this.request = request;
     }
 
+    /**
+     * 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)
+     * @see StoreApi#deleteOrder
+     */
     public ResponseEntity<Void> deleteOrder(@ApiParam(value = "ID of the order that needs to be deleted",required=true) @PathVariable("order_id") String orderId) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * GET /store/inventory : Returns pet inventories by status
+     * Returns a map of status codes to quantities
+     *
+     * @return successful operation (status code 200)
+     * @see StoreApi#getInventory
+     */
     public ResponseEntity<Map<String, Integer>> getInventory() {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * 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)
+     * @see StoreApi#getOrderById
+     */
     public ResponseEntity<Order> getOrderById(@Min(1L) @Max(5L) @ApiParam(value = "ID of pet that needs to be fetched",required=true) @PathVariable("order_id") Long orderId) {
         for (MediaType mediaType: MediaType.parseMediaTypes(request.getHeader("Accept"))) {
             if (mediaType.isCompatibleWith(MediaType.valueOf("application/json"))) {
@@ -59,6 +85,14 @@ public class StoreApiController implements 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)
+     * @see StoreApi#placeOrder
+     */
     public ResponseEntity<Order> placeOrder(@ApiParam(value = "order placed for purchasing the pet" ,required=true )  @Valid @RequestBody Order body) {
         for (MediaType mediaType: MediaType.parseMediaTypes(request.getHeader("Accept"))) {
             if (mediaType.isCompatibleWith(MediaType.valueOf("application/json"))) {

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

@@ -28,6 +28,13 @@ import java.util.Map;
 @Api(value = "user", description = "the user API")
 public interface UserApi {
 
+    /**
+     * 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") })
@@ -36,6 +43,12 @@ public interface UserApi {
     ResponseEntity<Void> createUser(@ApiParam(value = "Created user object" ,required=true )  @Valid @RequestBody User body);
 
 
+    /**
+     * 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") })
@@ -44,6 +57,12 @@ public interface UserApi {
     ResponseEntity<Void> createUsersWithArrayInput(@ApiParam(value = "List of user object" ,required=true )  @Valid @RequestBody List<User> body);
 
 
+    /**
+     * 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") })
@@ -52,6 +71,14 @@ public interface UserApi {
     ResponseEntity<Void> createUsersWithListInput(@ApiParam(value = "List of user object" ,required=true )  @Valid @RequestBody List<User> body);
 
 
+    /**
+     * 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"),
@@ -61,6 +88,14 @@ public interface UserApi {
     ResponseEntity<Void> deleteUser(@ApiParam(value = "The name that needs to be deleted",required=true) @PathVariable("username") String username);
 
 
+    /**
+     * 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),
@@ -72,6 +107,14 @@ public interface UserApi {
     ResponseEntity<User> getUserByName(@ApiParam(value = "The name that needs to be fetched. Use user1 for testing.",required=true) @PathVariable("username") String username);
 
 
+    /**
+     * 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),
@@ -82,6 +125,11 @@ public interface UserApi {
     ResponseEntity<String> loginUser(@NotNull @ApiParam(value = "The user name for login", required = true) @Valid @RequestParam(value = "username", required = true) String username,@NotNull @ApiParam(value = "The password for login in clear text", required = true) @Valid @RequestParam(value = "password", required = true) String password);
 
 
+    /**
+     * 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") })
@@ -90,6 +138,15 @@ public interface UserApi {
     ResponseEntity<Void> logoutUser();
 
 
+    /**
+     * 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"),

samples/server/petstore/spring-mvc/src/main/java/org/openapitools/api/UserApiController.java

@@ -32,26 +32,66 @@ public class UserApiController implements UserApi {
         this.request = request;
     }
 
+    /**
+     * 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)
+     * @see UserApi#createUser
+     */
     public ResponseEntity<Void> createUser(@ApiParam(value = "Created user object" ,required=true )  @Valid @RequestBody User body) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * POST /user/createWithArray : Creates list of users with given input array
+     *
+     * @param body List of user object (required)
+     * @return successful operation (status code 200)
+     * @see UserApi#createUsersWithArrayInput
+     */
     public ResponseEntity<Void> createUsersWithArrayInput(@ApiParam(value = "List of user object" ,required=true )  @Valid @RequestBody List<User> body) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * POST /user/createWithList : Creates list of users with given input array
+     *
+     * @param body List of user object (required)
+     * @return successful operation (status code 200)
+     * @see UserApi#createUsersWithListInput
+     */
     public ResponseEntity<Void> createUsersWithListInput(@ApiParam(value = "List of user object" ,required=true )  @Valid @RequestBody List<User> body) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * 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)
+     * @see UserApi#deleteUser
+     */
     public ResponseEntity<Void> deleteUser(@ApiParam(value = "The name that needs to be deleted",required=true) @PathVariable("username") String username) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * 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)
+     * @see UserApi#getUserByName
+     */
     public ResponseEntity<User> getUserByName(@ApiParam(value = "The name that needs to be fetched. Use user1 for testing.",required=true) @PathVariable("username") String username) {
         for (MediaType mediaType: MediaType.parseMediaTypes(request.getHeader("Accept"))) {
             if (mediaType.isCompatibleWith(MediaType.valueOf("application/json"))) {
@@ -69,16 +109,41 @@ public class UserApiController implements 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)
+     * @see UserApi#loginUser
+     */
     public ResponseEntity<String> loginUser(@NotNull @ApiParam(value = "The user name for login", required = true) @Valid @RequestParam(value = "username", required = true) String username,@NotNull @ApiParam(value = "The password for login in clear text", required = true) @Valid @RequestParam(value = "password", required = true) String password) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * GET /user/logout : Logs out current logged in user session
+     *
+     * @return successful operation (status code 200)
+     * @see UserApi#logoutUser
+     */
     public ResponseEntity<Void> logoutUser() {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * 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)
+     * @see UserApi#updateUser
+     */
     public ResponseEntity<Void> updateUser(@ApiParam(value = "name that need to be deleted",required=true) @PathVariable("username") String username,@ApiParam(value = "Updated user object" ,required=true )  @Valid @RequestBody User body) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 

samples/server/petstore/springboot-beanvalidation/src/main/java/org/openapitools/api/AnotherFakeApi.java

@@ -27,6 +27,13 @@ import java.util.Map;
 @Api(value = "another-fake", description = "the another-fake API")
 public interface AnotherFakeApi {
 
+    /**
+     * 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/springboot-beanvalidation/src/main/java/org/openapitools/api/AnotherFakeApiController.java

@@ -31,6 +31,14 @@ public class AnotherFakeApiController implements AnotherFakeApi {
         this.request = request;
     }
 
+    /**
+     * 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)
+     * @see AnotherFakeApi#call123testSpecialTags
+     */
     public ResponseEntity<Client> call123testSpecialTags(@ApiParam(value = "client model" ,required=true )  @Valid @RequestBody Client body) {
         for (MediaType mediaType: MediaType.parseMediaTypes(request.getHeader("Accept"))) {
             if (mediaType.isCompatibleWith(MediaType.valueOf("application/json"))) {

samples/server/petstore/springboot-beanvalidation/src/main/java/org/openapitools/api/FakeApi.java

@@ -37,6 +37,13 @@ import java.util.Map;
 @Api(value = "fake", description = "the fake API")
 public interface FakeApi {
 
+    /**
+     * 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") })
@@ -46,6 +53,13 @@ public interface FakeApi {
     ResponseEntity<Void> createXmlItem(@ApiParam(value = "XmlItem Body" ,required=true )  @Valid @RequestBody XmlItem xmlItem);
 
 
+    /**
+     * 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) })
@@ -55,6 +69,13 @@ public interface FakeApi {
     ResponseEntity<Boolean> fakeOuterBooleanSerialize(@ApiParam(value = "Input boolean as post body"  )  @Valid @RequestBody Boolean body);
 
 
+    /**
+     * 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) })
@@ -64,6 +85,13 @@ public interface FakeApi {
     ResponseEntity<OuterComposite> fakeOuterCompositeSerialize(@ApiParam(value = "Input composite as post body"  )  @Valid @RequestBody OuterComposite body);
 
 
+    /**
+     * 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) })
@@ -73,6 +101,13 @@ public interface FakeApi {
     ResponseEntity<BigDecimal> fakeOuterNumberSerialize(@ApiParam(value = "Input number as post body"  )  @Valid @RequestBody BigDecimal body);
 
 
+    /**
+     * 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) })
@@ -82,6 +117,13 @@ public interface FakeApi {
     ResponseEntity<String> fakeOuterStringSerialize(@ApiParam(value = "Input string as post body"  )  @Valid @RequestBody String body);
 
 
+    /**
+     * PUT /fake/body-with-file-schema
+     * For this test, the body for this request much reference a schema named &#x60;File&#x60;.
+     *
+     * @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") })
@@ -91,6 +133,13 @@ public interface FakeApi {
     ResponseEntity<Void> testBodyWithFileSchema(@ApiParam(value = "" ,required=true )  @Valid @RequestBody FileSchemaTestClass body);
 
 
+    /**
+     * 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") })
@@ -100,6 +149,13 @@ public interface FakeApi {
     ResponseEntity<Void> testBodyWithQueryParams(@NotNull @ApiParam(value = "", required = true) @Valid @RequestParam(value = "query", required = true) String query,@ApiParam(value = "" ,required=true )  @Valid @RequestBody User body);
 
 
+    /**
+     * PATCH /fake : To test \&quot;client\&quot; model
+     * To test \&quot;client\&quot; 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) })
@@ -110,6 +166,27 @@ public interface FakeApi {
     ResponseEntity<Client> testClientModel(@ApiParam(value = "client model" ,required=true )  @Valid @RequestBody Client body);
 
 
+    /**
+     * 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", })
@@ -122,6 +199,21 @@ public interface FakeApi {
     ResponseEntity<Void> testEndpointParameters(@ApiParam(value = "None", required=true) @RequestParam(value="number", required=true)  BigDecimal number,@ApiParam(value = "None", required=true) @RequestParam(value="double", required=true)  Double _double,@ApiParam(value = "None", required=true) @RequestParam(value="pattern_without_delimiter", required=true)  String patternWithoutDelimiter,@ApiParam(value = "None", required=true) @RequestParam(value="byte", required=true)  byte[] _byte,@ApiParam(value = "None") @RequestParam(value="integer", required=false)  Integer integer,@ApiParam(value = "None") @RequestParam(value="int32", required=false)  Integer int32,@ApiParam(value = "None") @RequestParam(value="int64", required=false)  Long int64,@ApiParam(value = "None") @RequestParam(value="float", required=false)  Float _float,@ApiParam(value = "None") @RequestParam(value="string", required=false)  String string,@ApiParam(value = "file detail") @Valid @RequestPart("file") MultipartFile binary,@ApiParam(value = "None") @RequestParam(value="date", required=false)  LocalDate date,@ApiParam(value = "None") @RequestParam(value="dateTime", required=false)  OffsetDateTime dateTime,@ApiParam(value = "None") @RequestParam(value="password", required=false)  String password,@ApiParam(value = "None") @RequestParam(value="callback", required=false)  String paramCallback);
 
 
+    /**
+     * GET /fake : To test enum parameters
+     * To test enum parameters
+     *
+     * @param enumHeaderStringArray Header parameter enum test (string array) (optional, default to new ArrayList&lt;String&gt;())
+     * @param enumHeaderString Header parameter enum test (string) (optional, default to -efg)
+     * @param enumQueryStringArray Query parameter enum test (string array) (optional, default to new ArrayList&lt;String&gt;())
+     * @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"),
@@ -132,6 +224,18 @@ public interface FakeApi {
     ResponseEntity<Void> testEnumParameters(@ApiParam(value = "Header parameter enum test (string array)" , allowableValues=">, $") @RequestHeader(value="enum_header_string_array", required=false) List<String> enumHeaderStringArray,@ApiParam(value = "Header parameter enum test (string)" , allowableValues="_abc, -efg, (xyz)", defaultValue="-efg") @RequestHeader(value="enum_header_string", required=false) String enumHeaderString,@ApiParam(value = "Query parameter enum test (string array)", allowableValues = ">, $") @Valid @RequestParam(value = "enum_query_string_array", required = false) List<String> enumQueryStringArray,@ApiParam(value = "Query parameter enum test (string)", allowableValues = "_abc, -efg, (xyz)", defaultValue = "-efg") @Valid @RequestParam(value = "enum_query_string", required = false, defaultValue="-efg") String enumQueryString,@ApiParam(value = "Query parameter enum test (double)", allowableValues = "1, -2") @Valid @RequestParam(value = "enum_query_integer", required = false) Integer enumQueryInteger,@ApiParam(value = "Query parameter enum test (double)", allowableValues = "1.1, -1.2") @Valid @RequestParam(value = "enum_query_double", required = false) Double enumQueryDouble,@ApiParam(value = "Form parameter enum test (string array)", allowableValues=">, $") @RequestParam(value="enum_form_string_array", required=false)  List<String> enumFormStringArray,@ApiParam(value = "Form parameter enum test (string)", allowableValues="_abc, -efg, (xyz)", defaultValue="-efg") @RequestParam(value="enum_form_string", required=false)  String enumFormString);
 
 
+    /**
+     * 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") })
@@ -140,6 +244,12 @@ public interface FakeApi {
     ResponseEntity<Void> testGroupParameters(@NotNull @ApiParam(value = "Required String in group parameters", required = true) @Valid @RequestParam(value = "required_string_group", required = true) Integer requiredStringGroup,@ApiParam(value = "Required Boolean in group parameters" ,required=true) @RequestHeader(value="required_boolean_group", required=true) Boolean requiredBooleanGroup,@NotNull @ApiParam(value = "Required Integer in group parameters", required = true) @Valid @RequestParam(value = "required_int64_group", required = true) Long requiredInt64Group,@ApiParam(value = "String in group parameters") @Valid @RequestParam(value = "string_group", required = false) Integer stringGroup,@ApiParam(value = "Boolean in group parameters" ) @RequestHeader(value="boolean_group", required=false) Boolean booleanGroup,@ApiParam(value = "Integer in group parameters") @Valid @RequestParam(value = "int64_group", required = false) Long int64Group);
 
 
+    /**
+     * 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") })
@@ -149,6 +259,13 @@ public interface FakeApi {
     ResponseEntity<Void> testInlineAdditionalProperties(@ApiParam(value = "request body" ,required=true )  @Valid @RequestBody Map<String, String> param);
 
 
+    /**
+     * 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") })
@@ -158,6 +275,17 @@ public interface FakeApi {
     ResponseEntity<Void> testJsonFormData(@ApiParam(value = "field1", required=true) @RequestParam(value="param", required=true)  String param,@ApiParam(value = "field2", required=true) @RequestParam(value="param2", required=true)  String param2);
 
 
+    /**
+     * 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") })
@@ -166,6 +294,14 @@ public interface FakeApi {
     ResponseEntity<Void> testQueryParameterCollectionFormat(@NotNull @ApiParam(value = "", required = true) @Valid @RequestParam(value = "pipe", required = true) List<String> pipe,@NotNull @ApiParam(value = "", required = true) @Valid @RequestParam(value = "ioutil", required = true) List<String> ioutil,@NotNull @ApiParam(value = "", required = true) @Valid @RequestParam(value = "http", required = true) List<String> http,@NotNull @ApiParam(value = "", required = true) @Valid @RequestParam(value = "url", required = true) List<String> url,@NotNull @ApiParam(value = "", required = true) @Valid @RequestParam(value = "context", required = true) List<String> context);
 
 
+    /**
+     * 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/springboot-beanvalidation/src/main/java/org/openapitools/api/FakeApiController.java

@@ -41,16 +41,40 @@ public class FakeApiController implements FakeApi {
         this.request = request;
     }
 
+    /**
+     * POST /fake/create_xml_item : creates an XmlItem
+     * this route creates an XmlItem
+     *
+     * @param xmlItem XmlItem Body (required)
+     * @return successful operation (status code 200)
+     * @see FakeApi#createXmlItem
+     */
     public ResponseEntity<Void> createXmlItem(@ApiParam(value = "XmlItem Body" ,required=true )  @Valid @RequestBody XmlItem xmlItem) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * POST /fake/outer/boolean
+     * Test serialization of outer boolean types
+     *
+     * @param body Input boolean as post body (optional)
+     * @return Output boolean (status code 200)
+     * @see FakeApi#fakeOuterBooleanSerialize
+     */
     public ResponseEntity<Boolean> fakeOuterBooleanSerialize(@ApiParam(value = "Input boolean as post body"  )  @Valid @RequestBody Boolean body) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * 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)
+     * @see FakeApi#fakeOuterCompositeSerialize
+     */
     public ResponseEntity<OuterComposite> fakeOuterCompositeSerialize(@ApiParam(value = "Input composite as post body"  )  @Valid @RequestBody OuterComposite body) {
         for (MediaType mediaType: MediaType.parseMediaTypes(request.getHeader("Accept"))) {
             if (mediaType.isCompatibleWith(MediaType.valueOf("*/*"))) {
@@ -63,26 +87,66 @@ public class FakeApiController implements 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)
+     * @see FakeApi#fakeOuterNumberSerialize
+     */
     public ResponseEntity<BigDecimal> fakeOuterNumberSerialize(@ApiParam(value = "Input number as post body"  )  @Valid @RequestBody BigDecimal body) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * POST /fake/outer/string
+     * Test serialization of outer string types
+     *
+     * @param body Input string as post body (optional)
+     * @return Output string (status code 200)
+     * @see FakeApi#fakeOuterStringSerialize
+     */
     public ResponseEntity<String> fakeOuterStringSerialize(@ApiParam(value = "Input string as post body"  )  @Valid @RequestBody String body) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * PUT /fake/body-with-file-schema
+     * For this test, the body for this request much reference a schema named &#x60;File&#x60;.
+     *
+     * @param body  (required)
+     * @return Success (status code 200)
+     * @see FakeApi#testBodyWithFileSchema
+     */
     public ResponseEntity<Void> testBodyWithFileSchema(@ApiParam(value = "" ,required=true )  @Valid @RequestBody FileSchemaTestClass body) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * PUT /fake/body-with-query-params
+     *
+     * @param query  (required)
+     * @param body  (required)
+     * @return Success (status code 200)
+     * @see FakeApi#testBodyWithQueryParams
+     */
     public ResponseEntity<Void> testBodyWithQueryParams(@NotNull @ApiParam(value = "", required = true) @Valid @RequestParam(value = "query", required = true) String query,@ApiParam(value = "" ,required=true )  @Valid @RequestBody User body) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * PATCH /fake : To test \&quot;client\&quot; model
+     * To test \&quot;client\&quot; model
+     *
+     * @param body client model (required)
+     * @return successful operation (status code 200)
+     * @see FakeApi#testClientModel
+     */
     public ResponseEntity<Client> testClientModel(@ApiParam(value = "client model" ,required=true )  @Valid @RequestBody Client body) {
         for (MediaType mediaType: MediaType.parseMediaTypes(request.getHeader("Accept"))) {
             if (mediaType.isCompatibleWith(MediaType.valueOf("application/json"))) {
@@ -95,36 +159,123 @@ public class FakeApiController implements 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)
+     * @see FakeApi#testEndpointParameters
+     */
     public ResponseEntity<Void> testEndpointParameters(@ApiParam(value = "None", required=true) @RequestParam(value="number", required=true)  BigDecimal number,@ApiParam(value = "None", required=true) @RequestParam(value="double", required=true)  Double _double,@ApiParam(value = "None", required=true) @RequestParam(value="pattern_without_delimiter", required=true)  String patternWithoutDelimiter,@ApiParam(value = "None", required=true) @RequestParam(value="byte", required=true)  byte[] _byte,@ApiParam(value = "None") @RequestParam(value="integer", required=false)  Integer integer,@ApiParam(value = "None") @RequestParam(value="int32", required=false)  Integer int32,@ApiParam(value = "None") @RequestParam(value="int64", required=false)  Long int64,@ApiParam(value = "None") @RequestParam(value="float", required=false)  Float _float,@ApiParam(value = "None") @RequestParam(value="string", required=false)  String string,@ApiParam(value = "file detail") @Valid @RequestPart("file") MultipartFile binary,@ApiParam(value = "None") @RequestParam(value="date", required=false)  LocalDate date,@ApiParam(value = "None") @RequestParam(value="dateTime", required=false)  OffsetDateTime dateTime,@ApiParam(value = "None") @RequestParam(value="password", required=false)  String password,@ApiParam(value = "None") @RequestParam(value="callback", required=false)  String paramCallback) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * GET /fake : To test enum parameters
+     * To test enum parameters
+     *
+     * @param enumHeaderStringArray Header parameter enum test (string array) (optional, default to new ArrayList&lt;String&gt;())
+     * @param enumHeaderString Header parameter enum test (string) (optional, default to -efg)
+     * @param enumQueryStringArray Query parameter enum test (string array) (optional, default to new ArrayList&lt;String&gt;())
+     * @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)
+     * @see FakeApi#testEnumParameters
+     */
     public ResponseEntity<Void> testEnumParameters(@ApiParam(value = "Header parameter enum test (string array)" , allowableValues=">, $") @RequestHeader(value="enum_header_string_array", required=false) List<String> enumHeaderStringArray,@ApiParam(value = "Header parameter enum test (string)" , allowableValues="_abc, -efg, (xyz)", defaultValue="-efg") @RequestHeader(value="enum_header_string", required=false) String enumHeaderString,@ApiParam(value = "Query parameter enum test (string array)", allowableValues = ">, $") @Valid @RequestParam(value = "enum_query_string_array", required = false) List<String> enumQueryStringArray,@ApiParam(value = "Query parameter enum test (string)", allowableValues = "_abc, -efg, (xyz)", defaultValue = "-efg") @Valid @RequestParam(value = "enum_query_string", required = false, defaultValue="-efg") String enumQueryString,@ApiParam(value = "Query parameter enum test (double)", allowableValues = "1, -2") @Valid @RequestParam(value = "enum_query_integer", required = false) Integer enumQueryInteger,@ApiParam(value = "Query parameter enum test (double)", allowableValues = "1.1, -1.2") @Valid @RequestParam(value = "enum_query_double", required = false) Double enumQueryDouble,@ApiParam(value = "Form parameter enum test (string array)", allowableValues=">, $") @RequestParam(value="enum_form_string_array", required=false)  List<String> enumFormStringArray,@ApiParam(value = "Form parameter enum test (string)", allowableValues="_abc, -efg, (xyz)", defaultValue="-efg") @RequestParam(value="enum_form_string", required=false)  String enumFormString) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * 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)
+     * @see FakeApi#testGroupParameters
+     */
     public ResponseEntity<Void> testGroupParameters(@NotNull @ApiParam(value = "Required String in group parameters", required = true) @Valid @RequestParam(value = "required_string_group", required = true) Integer requiredStringGroup,@ApiParam(value = "Required Boolean in group parameters" ,required=true) @RequestHeader(value="required_boolean_group", required=true) Boolean requiredBooleanGroup,@NotNull @ApiParam(value = "Required Integer in group parameters", required = true) @Valid @RequestParam(value = "required_int64_group", required = true) Long requiredInt64Group,@ApiParam(value = "String in group parameters") @Valid @RequestParam(value = "string_group", required = false) Integer stringGroup,@ApiParam(value = "Boolean in group parameters" ) @RequestHeader(value="boolean_group", required=false) Boolean booleanGroup,@ApiParam(value = "Integer in group parameters") @Valid @RequestParam(value = "int64_group", required = false) Long int64Group) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * POST /fake/inline-additionalProperties : test inline additionalProperties
+     *
+     * @param param request body (required)
+     * @return successful operation (status code 200)
+     * @see FakeApi#testInlineAdditionalProperties
+     */
     public ResponseEntity<Void> testInlineAdditionalProperties(@ApiParam(value = "request body" ,required=true )  @Valid @RequestBody Map<String, String> param) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * GET /fake/jsonFormData : test json serialization of form data
+     *
+     * @param param field1 (required)
+     * @param param2 field2 (required)
+     * @return successful operation (status code 200)
+     * @see FakeApi#testJsonFormData
+     */
     public ResponseEntity<Void> testJsonFormData(@ApiParam(value = "field1", required=true) @RequestParam(value="param", required=true)  String param,@ApiParam(value = "field2", required=true) @RequestParam(value="param2", required=true)  String param2) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * 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)
+     * @see FakeApi#testQueryParameterCollectionFormat
+     */
     public ResponseEntity<Void> testQueryParameterCollectionFormat(@NotNull @ApiParam(value = "", required = true) @Valid @RequestParam(value = "pipe", required = true) List<String> pipe,@NotNull @ApiParam(value = "", required = true) @Valid @RequestParam(value = "ioutil", required = true) List<String> ioutil,@NotNull @ApiParam(value = "", required = true) @Valid @RequestParam(value = "http", required = true) List<String> http,@NotNull @ApiParam(value = "", required = true) @Valid @RequestParam(value = "url", required = true) List<String> url,@NotNull @ApiParam(value = "", required = true) @Valid @RequestParam(value = "context", required = true) List<String> context) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * 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)
+     * @see FakeApi#uploadFileWithRequiredFile
+     */
     public ResponseEntity<ModelApiResponse> uploadFileWithRequiredFile(@ApiParam(value = "ID of pet to update",required=true) @PathVariable("petId") Long petId,@ApiParam(value = "file detail") @Valid @RequestPart("file") MultipartFile requiredFile,@ApiParam(value = "Additional data to pass to server") @RequestParam(value="additionalMetadata", required=false)  String additionalMetadata) {
         for (MediaType mediaType: MediaType.parseMediaTypes(request.getHeader("Accept"))) {
             if (mediaType.isCompatibleWith(MediaType.valueOf("application/json"))) {

samples/server/petstore/springboot-beanvalidation/src/main/java/org/openapitools/api/FakeClassnameTestApi.java

@@ -27,6 +27,13 @@ import java.util.Map;
 @Api(value = "fake_classname_test", description = "the fake_classname_test API")
 public interface FakeClassnameTestApi {
 
+    /**
+     * 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/springboot-beanvalidation/src/main/java/org/openapitools/api/FakeClassnameTestApiController.java

@@ -31,6 +31,14 @@ public class FakeClassnameTestApiController implements FakeClassnameTestApi {
         this.request = request;
     }
 
+    /**
+     * 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)
+     * @see FakeClassnameTestApi#testClassname
+     */
     public ResponseEntity<Client> testClassname(@ApiParam(value = "client model" ,required=true )  @Valid @RequestBody Client body) {
         for (MediaType mediaType: MediaType.parseMediaTypes(request.getHeader("Accept"))) {
             if (mediaType.isCompatibleWith(MediaType.valueOf("application/json"))) {

samples/server/petstore/springboot-beanvalidation/src/main/java/org/openapitools/api/PetApi.java

@@ -29,6 +29,13 @@ import java.util.Map;
 @Api(value = "pet", description = "the pet API")
 public interface PetApi {
 
+    /**
+     * 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"),
@@ -44,6 +51,14 @@ public interface PetApi {
     ResponseEntity<Void> addPet(@ApiParam(value = "Pet object that needs to be added to the store" ,required=true )  @Valid @RequestBody Pet body);
 
 
+    /**
+     * 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"),
@@ -58,6 +73,14 @@ public interface PetApi {
     ResponseEntity<Void> deletePet(@ApiParam(value = "Pet id to delete",required=true) @PathVariable("petId") Long petId,@ApiParam(value = "" ) @RequestHeader(value="api_key", required=false) String apiKey);
 
 
+    /**
+     * 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"),
@@ -73,6 +96,15 @@ public interface PetApi {
     ResponseEntity<List<Pet>> findPetsByStatus(@NotNull @ApiParam(value = "Status values that need to be considered for filter", required = true, allowableValues = "available, pending, sold") @Valid @RequestParam(value = "status", required = true) List<String> status);
 
 
+    /**
+     * 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"),
@@ -88,6 +120,15 @@ public interface PetApi {
     ResponseEntity<List<Pet>> findPetsByTags(@NotNull @ApiParam(value = "Tags to filter by", required = true) @Valid @RequestParam(value = "tags", required = true) List<String> tags);
 
 
+    /**
+     * 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", })
@@ -101,6 +142,15 @@ public interface PetApi {
     ResponseEntity<Pet> getPetById(@ApiParam(value = "ID of pet to return",required=true) @PathVariable("petId") Long petId);
 
 
+    /**
+     * 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"),
@@ -118,6 +168,14 @@ public interface PetApi {
     ResponseEntity<Void> updatePet(@ApiParam(value = "Pet object that needs to be added to the store" ,required=true )  @Valid @RequestBody Pet body);
 
 
+    /**
+     * 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"),
@@ -132,6 +190,14 @@ public interface PetApi {
     ResponseEntity<Void> updatePetWithForm(@ApiParam(value = "ID of pet that needs to be updated",required=true) @PathVariable("petId") Long petId,@ApiParam(value = "Updated name of the pet") @RequestParam(value="name", required=false)  String name,@ApiParam(value = "Updated status of the pet") @RequestParam(value="status", required=false)  String status);
 
 
+    /**
+     * 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/springboot-beanvalidation/src/main/java/org/openapitools/api/PetApiController.java

@@ -33,16 +33,42 @@ public class PetApiController implements PetApi {
         this.request = request;
     }
 
+    /**
+     * 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)
+     * @see PetApi#addPet
+     */
     public ResponseEntity<Void> addPet(@ApiParam(value = "Pet object that needs to be added to the store" ,required=true )  @Valid @RequestBody Pet body) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * 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)
+     * @see PetApi#deletePet
+     */
     public ResponseEntity<Void> deletePet(@ApiParam(value = "Pet id to delete",required=true) @PathVariable("petId") Long petId,@ApiParam(value = "" ) @RequestHeader(value="api_key", required=false) String apiKey) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * 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)
+     * @see PetApi#findPetsByStatus
+     */
     public ResponseEntity<List<Pet>> findPetsByStatus(@NotNull @ApiParam(value = "Status values that need to be considered for filter", required = true, allowableValues = "available, pending, sold") @Valid @RequestParam(value = "status", required = true) List<String> status) {
         for (MediaType mediaType: MediaType.parseMediaTypes(request.getHeader("Accept"))) {
             if (mediaType.isCompatibleWith(MediaType.valueOf("application/json"))) {
@@ -60,6 +86,16 @@ public class PetApiController implements 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
+     * @see PetApi#findPetsByTags
+     */
     public ResponseEntity<List<Pet>> findPetsByTags(@NotNull @ApiParam(value = "Tags to filter by", required = true) @Valid @RequestParam(value = "tags", required = true) List<String> tags) {
         for (MediaType mediaType: MediaType.parseMediaTypes(request.getHeader("Accept"))) {
             if (mediaType.isCompatibleWith(MediaType.valueOf("application/json"))) {
@@ -77,6 +113,16 @@ public class PetApiController implements 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)
+     * @see PetApi#getPetById
+     */
     public ResponseEntity<Pet> getPetById(@ApiParam(value = "ID of pet to return",required=true) @PathVariable("petId") Long petId) {
         for (MediaType mediaType: MediaType.parseMediaTypes(request.getHeader("Accept"))) {
             if (mediaType.isCompatibleWith(MediaType.valueOf("application/json"))) {
@@ -94,16 +140,44 @@ public class PetApiController implements 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)
+     * @see PetApi#updatePet
+     */
     public ResponseEntity<Void> updatePet(@ApiParam(value = "Pet object that needs to be added to the store" ,required=true )  @Valid @RequestBody Pet body) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * 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)
+     * @see PetApi#updatePetWithForm
+     */
     public ResponseEntity<Void> updatePetWithForm(@ApiParam(value = "ID of pet that needs to be updated",required=true) @PathVariable("petId") Long petId,@ApiParam(value = "Updated name of the pet") @RequestParam(value="name", required=false)  String name,@ApiParam(value = "Updated status of the pet") @RequestParam(value="status", required=false)  String status) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * 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)
+     * @see PetApi#uploadFile
+     */
     public ResponseEntity<ModelApiResponse> uploadFile(@ApiParam(value = "ID of pet to update",required=true) @PathVariable("petId") Long petId,@ApiParam(value = "Additional data to pass to server") @RequestParam(value="additionalMetadata", required=false)  String additionalMetadata,@ApiParam(value = "file detail") @Valid @RequestPart("file") MultipartFile file) {
         for (MediaType mediaType: MediaType.parseMediaTypes(request.getHeader("Accept"))) {
             if (mediaType.isCompatibleWith(MediaType.valueOf("application/json"))) {

samples/server/petstore/springboot-beanvalidation/src/main/java/org/openapitools/api/StoreApi.java

@@ -28,6 +28,14 @@ import java.util.Map;
 @Api(value = "store", description = "the store API")
 public interface StoreApi {
 
+    /**
+     * 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"),
@@ -37,6 +45,12 @@ public interface StoreApi {
     ResponseEntity<Void> deleteOrder(@ApiParam(value = "ID of the order that needs to be deleted",required=true) @PathVariable("order_id") String orderId);
 
 
+    /**
+     * 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", })
@@ -48,6 +62,15 @@ public interface StoreApi {
     ResponseEntity<Map<String, Integer>> getInventory();
 
 
+    /**
+     * 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),
@@ -59,6 +82,13 @@ public interface StoreApi {
     ResponseEntity<Order> getOrderById(@Min(1L) @Max(5L) @ApiParam(value = "ID of pet that needs to be fetched",required=true) @PathVariable("order_id") Long orderId);
 
 
+    /**
+     * 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/springboot-beanvalidation/src/main/java/org/openapitools/api/StoreApiController.java

@@ -32,16 +32,42 @@ public class StoreApiController implements StoreApi {
         this.request = request;
     }
 
+    /**
+     * 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)
+     * @see StoreApi#deleteOrder
+     */
     public ResponseEntity<Void> deleteOrder(@ApiParam(value = "ID of the order that needs to be deleted",required=true) @PathVariable("order_id") String orderId) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * GET /store/inventory : Returns pet inventories by status
+     * Returns a map of status codes to quantities
+     *
+     * @return successful operation (status code 200)
+     * @see StoreApi#getInventory
+     */
     public ResponseEntity<Map<String, Integer>> getInventory() {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * 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)
+     * @see StoreApi#getOrderById
+     */
     public ResponseEntity<Order> getOrderById(@Min(1L) @Max(5L) @ApiParam(value = "ID of pet that needs to be fetched",required=true) @PathVariable("order_id") Long orderId) {
         for (MediaType mediaType: MediaType.parseMediaTypes(request.getHeader("Accept"))) {
             if (mediaType.isCompatibleWith(MediaType.valueOf("application/json"))) {
@@ -59,6 +85,14 @@ public class StoreApiController implements 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)
+     * @see StoreApi#placeOrder
+     */
     public ResponseEntity<Order> placeOrder(@ApiParam(value = "order placed for purchasing the pet" ,required=true )  @Valid @RequestBody Order body) {
         for (MediaType mediaType: MediaType.parseMediaTypes(request.getHeader("Accept"))) {
             if (mediaType.isCompatibleWith(MediaType.valueOf("application/json"))) {

samples/server/petstore/springboot-beanvalidation/src/main/java/org/openapitools/api/UserApi.java

@@ -28,6 +28,13 @@ import java.util.Map;
 @Api(value = "user", description = "the user API")
 public interface UserApi {
 
+    /**
+     * 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") })
@@ -36,6 +43,12 @@ public interface UserApi {
     ResponseEntity<Void> createUser(@ApiParam(value = "Created user object" ,required=true )  @Valid @RequestBody User body);
 
 
+    /**
+     * 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") })
@@ -44,6 +57,12 @@ public interface UserApi {
     ResponseEntity<Void> createUsersWithArrayInput(@ApiParam(value = "List of user object" ,required=true )  @Valid @RequestBody List<User> body);
 
 
+    /**
+     * 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") })
@@ -52,6 +71,14 @@ public interface UserApi {
     ResponseEntity<Void> createUsersWithListInput(@ApiParam(value = "List of user object" ,required=true )  @Valid @RequestBody List<User> body);
 
 
+    /**
+     * 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"),
@@ -61,6 +88,14 @@ public interface UserApi {
     ResponseEntity<Void> deleteUser(@ApiParam(value = "The name that needs to be deleted",required=true) @PathVariable("username") String username);
 
 
+    /**
+     * 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),
@@ -72,6 +107,14 @@ public interface UserApi {
     ResponseEntity<User> getUserByName(@ApiParam(value = "The name that needs to be fetched. Use user1 for testing.",required=true) @PathVariable("username") String username);
 
 
+    /**
+     * 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),
@@ -82,6 +125,11 @@ public interface UserApi {
     ResponseEntity<String> loginUser(@NotNull @ApiParam(value = "The user name for login", required = true) @Valid @RequestParam(value = "username", required = true) String username,@NotNull @ApiParam(value = "The password for login in clear text", required = true) @Valid @RequestParam(value = "password", required = true) String password);
 
 
+    /**
+     * 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") })
@@ -90,6 +138,15 @@ public interface UserApi {
     ResponseEntity<Void> logoutUser();
 
 
+    /**
+     * 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"),

samples/server/petstore/springboot-beanvalidation/src/main/java/org/openapitools/api/UserApiController.java

@@ -32,26 +32,66 @@ public class UserApiController implements UserApi {
         this.request = request;
     }
 
+    /**
+     * 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)
+     * @see UserApi#createUser
+     */
     public ResponseEntity<Void> createUser(@ApiParam(value = "Created user object" ,required=true )  @Valid @RequestBody User body) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * POST /user/createWithArray : Creates list of users with given input array
+     *
+     * @param body List of user object (required)
+     * @return successful operation (status code 200)
+     * @see UserApi#createUsersWithArrayInput
+     */
     public ResponseEntity<Void> createUsersWithArrayInput(@ApiParam(value = "List of user object" ,required=true )  @Valid @RequestBody List<User> body) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * POST /user/createWithList : Creates list of users with given input array
+     *
+     * @param body List of user object (required)
+     * @return successful operation (status code 200)
+     * @see UserApi#createUsersWithListInput
+     */
     public ResponseEntity<Void> createUsersWithListInput(@ApiParam(value = "List of user object" ,required=true )  @Valid @RequestBody List<User> body) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * 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)
+     * @see UserApi#deleteUser
+     */
     public ResponseEntity<Void> deleteUser(@ApiParam(value = "The name that needs to be deleted",required=true) @PathVariable("username") String username) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * 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)
+     * @see UserApi#getUserByName
+     */
     public ResponseEntity<User> getUserByName(@ApiParam(value = "The name that needs to be fetched. Use user1 for testing.",required=true) @PathVariable("username") String username) {
         for (MediaType mediaType: MediaType.parseMediaTypes(request.getHeader("Accept"))) {
             if (mediaType.isCompatibleWith(MediaType.valueOf("application/json"))) {
@@ -69,16 +109,41 @@ public class UserApiController implements 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)
+     * @see UserApi#loginUser
+     */
     public ResponseEntity<String> loginUser(@NotNull @ApiParam(value = "The user name for login", required = true) @Valid @RequestParam(value = "username", required = true) String username,@NotNull @ApiParam(value = "The password for login in clear text", required = true) @Valid @RequestParam(value = "password", required = true) String password) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * GET /user/logout : Logs out current logged in user session
+     *
+     * @return successful operation (status code 200)
+     * @see UserApi#logoutUser
+     */
     public ResponseEntity<Void> logoutUser() {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 
     }
 
+    /**
+     * 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)
+     * @see UserApi#updateUser
+     */
     public ResponseEntity<Void> updateUser(@ApiParam(value = "name that need to be deleted",required=true) @PathVariable("username") String username,@ApiParam(value = "Updated user object" ,required=true )  @Valid @RequestBody User body) {
         return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);
 

samples/server/petstore/springboot-delegate-j8/src/main/java/org/openapitools/api/AnotherFakeApi.java

@@ -31,6 +31,13 @@ public interface AnotherFakeApi {
         return new AnotherFakeApiDelegate() {};
     }
 
+    /**
+     * 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/springboot-delegate-j8/src/main/java/org/openapitools/api/AnotherFakeApiDelegate.java

@@ -24,6 +24,11 @@ public interface AnotherFakeApiDelegate {
     }
 
     /**
+     * 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)
      * @see AnotherFakeApi#call123testSpecialTags
      */
     default ResponseEntity<Client> call123testSpecialTags(Client body) {

samples/server/petstore/springboot-delegate-j8/src/main/java/org/openapitools/api/FakeApi.java

@@ -41,6 +41,13 @@ public interface FakeApi {
         return new FakeApiDelegate() {};
     }
 
+    /**
+     * 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") })
@@ -52,6 +59,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) })
@@ -63,6 +77,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) })
@@ -74,6 +95,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) })
@@ -85,6 +113,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) })
@@ -96,6 +131,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") })
@@ -107,6 +149,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") })
@@ -118,6 +167,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) })
@@ -130,6 +186,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", })
@@ -144,6 +221,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"),
@@ -156,6 +248,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") })
@@ -166,6 +270,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") })
@@ -177,6 +287,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") })
@@ -188,6 +305,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") })
@@ -198,6 +326,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/springboot-delegate-j8/src/main/java/org/openapitools/api/FakeApiDelegate.java

@@ -34,6 +34,11 @@ public interface FakeApiDelegate {
     }
 
     /**
+     * POST /fake/create_xml_item : creates an XmlItem
+     * this route creates an XmlItem
+     *
+     * @param xmlItem XmlItem Body (required)
+     * @return successful operation (status code 200)
      * @see FakeApi#createXmlItem
      */
     default ResponseEntity<Void> createXmlItem(XmlItem xmlItem) {
@@ -42,6 +47,11 @@ public interface FakeApiDelegate {
     }
 
     /**
+     * POST /fake/outer/boolean
+     * Test serialization of outer boolean types
+     *
+     * @param body Input boolean as post body (optional)
+     * @return Output boolean (status code 200)
      * @see FakeApi#fakeOuterBooleanSerialize
      */
     default ResponseEntity<Boolean> fakeOuterBooleanSerialize(Boolean body) {
@@ -50,6 +60,11 @@ public interface FakeApiDelegate {
     }
 
     /**
+     * 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)
      * @see FakeApi#fakeOuterCompositeSerialize
      */
     default ResponseEntity<OuterComposite> fakeOuterCompositeSerialize(OuterComposite body) {
@@ -67,6 +82,11 @@ public interface FakeApiDelegate {
     }
 
     /**
+     * POST /fake/outer/number
+     * Test serialization of outer number types
+     *
+     * @param body Input number as post body (optional)
+     * @return Output number (status code 200)
      * @see FakeApi#fakeOuterNumberSerialize
      */
     default ResponseEntity<BigDecimal> fakeOuterNumberSerialize(BigDecimal body) {
@@ -75,6 +95,11 @@ public interface FakeApiDelegate {
     }
 
     /**
+     * POST /fake/outer/string
+     * Test serialization of outer string types
+     *
+     * @param body Input string as post body (optional)
+     * @return Output string (status code 200)
      * @see FakeApi#fakeOuterStringSerialize
      */
     default ResponseEntity<String> fakeOuterStringSerialize(String body) {
@@ -83,6 +108,11 @@ public interface FakeApiDelegate {
     }
 
     /**
+     * PUT /fake/body-with-file-schema
+     * For this test, the body for this request much reference a schema named &#x60;File&#x60;.
+     *
+     * @param body  (required)
+     * @return Success (status code 200)
      * @see FakeApi#testBodyWithFileSchema
      */
     default ResponseEntity<Void> testBodyWithFileSchema(FileSchemaTestClass body) {
@@ -91,6 +121,11 @@ public interface FakeApiDelegate {
     }
 
     /**
+     * PUT /fake/body-with-query-params
+     *
+     * @param query  (required)
+     * @param body  (required)
+     * @return Success (status code 200)
      * @see FakeApi#testBodyWithQueryParams
      */
     default ResponseEntity<Void> testBodyWithQueryParams(String query,
@@ -100,6 +135,11 @@ public interface FakeApiDelegate {
     }
 
     /**
+     * PATCH /fake : To test \&quot;client\&quot; model
+     * To test \&quot;client\&quot; model
+     *
+     * @param body client model (required)
+     * @return successful operation (status code 200)
      * @see FakeApi#testClientModel
      */
     default ResponseEntity<Client> testClientModel(Client body) {
@@ -117,6 +157,25 @@ public interface FakeApiDelegate {
     }
 
     /**
+     * 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)
      * @see FakeApi#testEndpointParameters
      */
     default ResponseEntity<Void> testEndpointParameters(BigDecimal number,
@@ -138,6 +197,19 @@ public interface FakeApiDelegate {
     }
 
     /**
+     * GET /fake : To test enum parameters
+     * To test enum parameters
+     *
+     * @param enumHeaderStringArray Header parameter enum test (string array) (optional, default to new ArrayList&lt;&gt;())
+     * @param enumHeaderString Header parameter enum test (string) (optional, default to -efg)
+     * @param enumQueryStringArray Query parameter enum test (string array) (optional, default to new ArrayList&lt;&gt;())
+     * @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)
      * @see FakeApi#testEnumParameters
      */
     default ResponseEntity<Void> testEnumParameters(List<String> enumHeaderStringArray,
@@ -153,6 +225,16 @@ public interface FakeApiDelegate {
     }
 
     /**
+     * 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)
      * @see FakeApi#testGroupParameters
      */
     default ResponseEntity<Void> testGroupParameters(Integer requiredStringGroup,
@@ -166,6 +248,10 @@ public interface FakeApiDelegate {
     }
 
     /**
+     * POST /fake/inline-additionalProperties : test inline additionalProperties
+     *
+     * @param param request body (required)
+     * @return successful operation (status code 200)
      * @see FakeApi#testInlineAdditionalProperties
      */
     default ResponseEntity<Void> testInlineAdditionalProperties(Map<String, String> param) {
@@ -174,6 +260,11 @@ public interface FakeApiDelegate {
     }
 
     /**
+     * GET /fake/jsonFormData : test json serialization of form data
+     *
+     * @param param field1 (required)
+     * @param param2 field2 (required)
+     * @return successful operation (status code 200)
      * @see FakeApi#testJsonFormData
      */
     default ResponseEntity<Void> testJsonFormData(String param,
@@ -183,6 +274,15 @@ public interface FakeApiDelegate {
     }
 
     /**
+     * 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)
      * @see FakeApi#testQueryParameterCollectionFormat
      */
     default ResponseEntity<Void> testQueryParameterCollectionFormat(List<String> pipe,
@@ -195,6 +295,12 @@ public interface FakeApiDelegate {
     }
 
     /**
+     * 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)
      * @see FakeApi#uploadFileWithRequiredFile
      */
     default ResponseEntity<ModelApiResponse> uploadFileWithRequiredFile(Long petId,

samples/server/petstore/springboot-delegate-j8/src/main/java/org/openapitools/api/FakeClassnameTestApi.java

@@ -31,6 +31,13 @@ public interface FakeClassnameTestApi {
         return new FakeClassnameTestApiDelegate() {};
     }
 
+    /**
+     * 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/springboot-delegate-j8/src/main/java/org/openapitools/api/FakeClassnameTestApiDelegate.java

@@ -24,6 +24,11 @@ public interface FakeClassnameTestApiDelegate {
     }
 
     /**
+     * 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)
      * @see FakeClassnameTestApi#testClassname
      */
     default ResponseEntity<Client> testClassname(Client body) {

samples/server/petstore/springboot-delegate-j8/src/main/java/org/openapitools/api/PetApi.java

@@ -33,6 +33,13 @@ public interface PetApi {
         return new PetApiDelegate() {};
     }
 
+    /**
+     * 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"),
@@ -50,6 +57,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"),
@@ -66,6 +81,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"),
@@ -83,6 +106,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"),
@@ -100,6 +132,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", })
@@ -115,6 +156,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"),
@@ -134,6 +184,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"),
@@ -150,6 +208,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/springboot-delegate-j8/src/main/java/org/openapitools/api/PetApiDelegate.java

@@ -26,6 +26,11 @@ public interface PetApiDelegate {
     }
 
     /**
+     * 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)
      * @see PetApi#addPet
      */
     default ResponseEntity<Void> addPet(Pet body) {
@@ -34,6 +39,12 @@ public interface PetApiDelegate {
     }
 
     /**
+     * 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)
      * @see PetApi#deletePet
      */
     default ResponseEntity<Void> deletePet(Long petId,
@@ -43,6 +54,12 @@ public interface PetApiDelegate {
     }
 
     /**
+     * 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)
      * @see PetApi#findPetsByStatus
      */
     default ResponseEntity<List<Pet>> findPetsByStatus(List<String> status) {
@@ -65,6 +82,13 @@ public interface PetApiDelegate {
     }
 
     /**
+     * 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
      * @see PetApi#findPetsByTags
      */
     default ResponseEntity<List<Pet>> findPetsByTags(List<String> tags) {
@@ -87,6 +111,13 @@ public interface PetApiDelegate {
     }
 
     /**
+     * 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)
      * @see PetApi#getPetById
      */
     default ResponseEntity<Pet> getPetById(Long petId) {
@@ -109,6 +140,13 @@ public interface PetApiDelegate {
     }
 
     /**
+     * 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)
      * @see PetApi#updatePet
      */
     default ResponseEntity<Void> updatePet(Pet body) {
@@ -117,6 +155,12 @@ public interface PetApiDelegate {
     }
 
     /**
+     * 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)
      * @see PetApi#updatePetWithForm
      */
     default ResponseEntity<Void> updatePetWithForm(Long petId,
@@ -127,6 +171,12 @@ public interface PetApiDelegate {
     }
 
     /**
+     * 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)
      * @see PetApi#uploadFile
      */
     default ResponseEntity<ModelApiResponse> uploadFile(Long petId,

samples/server/petstore/springboot-delegate-j8/src/main/java/org/openapitools/api/StoreApi.java

@@ -32,6 +32,14 @@ public interface StoreApi {
         return new StoreApiDelegate() {};
     }
 
+    /**
+     * 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"),
@@ -43,6 +51,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", })
@@ -56,6 +70,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),
@@ -69,6 +92,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/springboot-delegate-j8/src/main/java/org/openapitools/api/StoreApiDelegate.java

@@ -25,6 +25,12 @@ public interface StoreApiDelegate {
     }
 
     /**
+     * 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)
      * @see StoreApi#deleteOrder
      */
     default ResponseEntity<Void> deleteOrder(String orderId) {
@@ -33,6 +39,10 @@ public interface StoreApiDelegate {
     }
 
     /**
+     * GET /store/inventory : Returns pet inventories by status
+     * Returns a map of status codes to quantities
+     *
+     * @return successful operation (status code 200)
      * @see StoreApi#getInventory
      */
     default ResponseEntity<Map<String, Integer>> getInventory() {
@@ -41,6 +51,13 @@ public interface StoreApiDelegate {
     }
 
     /**
+     * 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)
      * @see StoreApi#getOrderById
      */
     default ResponseEntity<Order> getOrderById(Long orderId) {
@@ -63,6 +80,11 @@ public interface StoreApiDelegate {
     }
 
     /**
+     * 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)
      * @see StoreApi#placeOrder
      */
     default ResponseEntity<Order> placeOrder(Order body) {

samples/server/petstore/springboot-delegate-j8/src/main/java/org/openapitools/api/UserApi.java

@@ -32,6 +32,13 @@ public interface UserApi {
         return new UserApiDelegate() {};
     }
 
+    /**
+     * 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") })
@@ -42,6 +49,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") })
@@ -52,6 +65,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") })
@@ -62,6 +81,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"),
@@ -73,6 +100,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),
@@ -86,6 +121,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),
@@ -98,6 +141,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") })
@@ -108,6 +156,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"),

samples/server/petstore/springboot-delegate-j8/src/main/java/org/openapitools/api/UserApiDelegate.java

@@ -25,6 +25,11 @@ public interface UserApiDelegate {
     }
 
     /**
+     * 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)
      * @see UserApi#createUser
      */
     default ResponseEntity<Void> createUser(User body) {
@@ -33,6 +38,10 @@ public interface UserApiDelegate {
     }
 
     /**
+     * POST /user/createWithArray : Creates list of users with given input array
+     *
+     * @param body List of user object (required)
+     * @return successful operation (status code 200)
      * @see UserApi#createUsersWithArrayInput
      */
     default ResponseEntity<Void> createUsersWithArrayInput(List<User> body) {
@@ -41,6 +50,10 @@ public interface UserApiDelegate {
     }
 
     /**
+     * POST /user/createWithList : Creates list of users with given input array
+     *
+     * @param body List of user object (required)
+     * @return successful operation (status code 200)
      * @see UserApi#createUsersWithListInput
      */
     default ResponseEntity<Void> createUsersWithListInput(List<User> body) {
@@ -49,6 +62,12 @@ public interface UserApiDelegate {
     }
 
     /**
+     * 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)
      * @see UserApi#deleteUser
      */
     default ResponseEntity<Void> deleteUser(String username) {
@@ -57,6 +76,12 @@ public interface UserApiDelegate {
     }
 
     /**
+     * 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)
      * @see UserApi#getUserByName
      */
     default ResponseEntity<User> getUserByName(String username) {
@@ -79,6 +104,12 @@ public interface UserApiDelegate {
     }
 
     /**
+     * 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)
      * @see UserApi#loginUser
      */
     default ResponseEntity<String> loginUser(String username,
@@ -88,6 +119,9 @@ public interface UserApiDelegate {
     }
 
     /**
+     * GET /user/logout : Logs out current logged in user session
+     *
+     * @return successful operation (status code 200)
      * @see UserApi#logoutUser
      */
     default ResponseEntity<Void> logoutUser() {
@@ -96,6 +130,13 @@ public interface UserApiDelegate {
     }
 
     /**
+     * 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)
      * @see UserApi#updateUser
      */
     default ResponseEntity<Void> updateUser(String username,

samples/server/petstore/springboot-delegate/src/main/java/org/openapitools/api/AnotherFakeApi.java

@@ -27,6 +27,13 @@ import java.util.Map;
 @Api(value = "another-fake", description = "the another-fake API")
 public interface AnotherFakeApi {
 
+    /**
+     * 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/springboot-delegate/src/main/java/org/openapitools/api/AnotherFakeApiController.java

@@ -29,6 +29,14 @@ public class AnotherFakeApiController implements AnotherFakeApi {
         this.delegate = delegate;
     }
 
+    /**
+     * 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)
+     * @see AnotherFakeApi#call123testSpecialTags
+     */
     public ResponseEntity<Client> call123testSpecialTags(@ApiParam(value = "client model" ,required=true )  @Valid @RequestBody Client body) {
         return delegate.call123testSpecialTags(body);
     }

samples/server/petstore/springboot-delegate/src/main/java/org/openapitools/api/AnotherFakeApiDelegate.java

@@ -16,6 +16,11 @@ import java.util.Map;
 public interface AnotherFakeApiDelegate {
 
     /**
+     * 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)
      * @see AnotherFakeApi#call123testSpecialTags
      */
     ResponseEntity<Client> call123testSpecialTags(Client body);

samples/server/petstore/springboot-delegate/src/main/java/org/openapitools/api/FakeApi.java

@@ -37,6 +37,13 @@ import java.util.Map;
 @Api(value = "fake", description = "the fake API")
 public interface FakeApi {
 
+    /**
+     * 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") })
@@ -46,6 +53,13 @@ public interface FakeApi {
     ResponseEntity<Void> createXmlItem(@ApiParam(value = "XmlItem Body" ,required=true )  @Valid @RequestBody XmlItem xmlItem);
 
 
+    /**
+     * 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) })
@@ -55,6 +69,13 @@ public interface FakeApi {
     ResponseEntity<Boolean> fakeOuterBooleanSerialize(@ApiParam(value = "Input boolean as post body"  )  @Valid @RequestBody Boolean body);
 
 
+    /**
+     * 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) })
@@ -64,6 +85,13 @@ public interface FakeApi {
     ResponseEntity<OuterComposite> fakeOuterCompositeSerialize(@ApiParam(value = "Input composite as post body"  )  @Valid @RequestBody OuterComposite body);
 
 
+    /**
+     * 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) })
@@ -73,6 +101,13 @@ public interface FakeApi {
     ResponseEntity<BigDecimal> fakeOuterNumberSerialize(@ApiParam(value = "Input number as post body"  )  @Valid @RequestBody BigDecimal body);
 
 
+    /**
+     * 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) })
@@ -82,6 +117,13 @@ public interface FakeApi {
     ResponseEntity<String> fakeOuterStringSerialize(@ApiParam(value = "Input string as post body"  )  @Valid @RequestBody String body);
 
 
+    /**
+     * PUT /fake/body-with-file-schema
+     * For this test, the body for this request much reference a schema named &#x60;File&#x60;.
+     *
+     * @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") })
@@ -91,6 +133,13 @@ public interface FakeApi {
     ResponseEntity<Void> testBodyWithFileSchema(@ApiParam(value = "" ,required=true )  @Valid @RequestBody FileSchemaTestClass body);
 
 
+    /**
+     * 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") })
@@ -100,6 +149,13 @@ public interface FakeApi {
     ResponseEntity<Void> testBodyWithQueryParams(@NotNull @ApiParam(value = "", required = true) @Valid @RequestParam(value = "query", required = true) String query,@ApiParam(value = "" ,required=true )  @Valid @RequestBody User body);
 
 
+    /**
+     * PATCH /fake : To test \&quot;client\&quot; model
+     * To test \&quot;client\&quot; 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) })
@@ -110,6 +166,27 @@ public interface FakeApi {
     ResponseEntity<Client> testClientModel(@ApiParam(value = "client model" ,required=true )  @Valid @RequestBody Client body);
 
 
+    /**
+     * 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", })
@@ -122,6 +199,21 @@ public interface FakeApi {
     ResponseEntity<Void> testEndpointParameters(@ApiParam(value = "None", required=true) @RequestParam(value="number", required=true)  BigDecimal number,@ApiParam(value = "None", required=true) @RequestParam(value="double", required=true)  Double _double,@ApiParam(value = "None", required=true) @RequestParam(value="pattern_without_delimiter", required=true)  String patternWithoutDelimiter,@ApiParam(value = "None", required=true) @RequestParam(value="byte", required=true)  byte[] _byte,@ApiParam(value = "None") @RequestParam(value="integer", required=false)  Integer integer,@ApiParam(value = "None") @RequestParam(value="int32", required=false)  Integer int32,@ApiParam(value = "None") @RequestParam(value="int64", required=false)  Long int64,@ApiParam(value = "None") @RequestParam(value="float", required=false)  Float _float,@ApiParam(value = "None") @RequestParam(value="string", required=false)  String string,@ApiParam(value = "file detail") @Valid @RequestPart("file") MultipartFile binary,@ApiParam(value = "None") @RequestParam(value="date", required=false)  LocalDate date,@ApiParam(value = "None") @RequestParam(value="dateTime", required=false)  OffsetDateTime dateTime,@ApiParam(value = "None") @RequestParam(value="password", required=false)  String password,@ApiParam(value = "None") @RequestParam(value="callback", required=false)  String paramCallback);
 
 
+    /**
+     * GET /fake : To test enum parameters
+     * To test enum parameters
+     *
+     * @param enumHeaderStringArray Header parameter enum test (string array) (optional, default to new ArrayList&lt;String&gt;())
+     * @param enumHeaderString Header parameter enum test (string) (optional, default to -efg)
+     * @param enumQueryStringArray Query parameter enum test (string array) (optional, default to new ArrayList&lt;String&gt;())
+     * @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"),
@@ -132,6 +224,18 @@ public interface FakeApi {
     ResponseEntity<Void> testEnumParameters(@ApiParam(value = "Header parameter enum test (string array)" , allowableValues=">, $") @RequestHeader(value="enum_header_string_array", required=false) List<String> enumHeaderStringArray,@ApiParam(value = "Header parameter enum test (string)" , allowableValues="_abc, -efg, (xyz)", defaultValue="-efg") @RequestHeader(value="enum_header_string", required=false) String enumHeaderString,@ApiParam(value = "Query parameter enum test (string array)", allowableValues = ">, $") @Valid @RequestParam(value = "enum_query_string_array", required = false) List<String> enumQueryStringArray,@ApiParam(value = "Query parameter enum test (string)", allowableValues = "_abc, -efg, (xyz)", defaultValue = "-efg") @Valid @RequestParam(value = "enum_query_string", required = false, defaultValue="-efg") String enumQueryString,@ApiParam(value = "Query parameter enum test (double)", allowableValues = "1, -2") @Valid @RequestParam(value = "enum_query_integer", required = false) Integer enumQueryInteger,@ApiParam(value = "Query parameter enum test (double)", allowableValues = "1.1, -1.2") @Valid @RequestParam(value = "enum_query_double", required = false) Double enumQueryDouble,@ApiParam(value = "Form parameter enum test (string array)", allowableValues=">, $") @RequestParam(value="enum_form_string_array", required=false)  List<String> enumFormStringArray,@ApiParam(value = "Form parameter enum test (string)", allowableValues="_abc, -efg, (xyz)", defaultValue="-efg") @RequestParam(value="enum_form_string", required=false)  String enumFormString);
 
 
+    /**
+     * 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") })
@@ -140,6 +244,12 @@ public interface FakeApi {
     ResponseEntity<Void> testGroupParameters(@NotNull @ApiParam(value = "Required String in group parameters", required = true) @Valid @RequestParam(value = "required_string_group", required = true) Integer requiredStringGroup,@ApiParam(value = "Required Boolean in group parameters" ,required=true) @RequestHeader(value="required_boolean_group", required=true) Boolean requiredBooleanGroup,@NotNull @ApiParam(value = "Required Integer in group parameters", required = true) @Valid @RequestParam(value = "required_int64_group", required = true) Long requiredInt64Group,@ApiParam(value = "String in group parameters") @Valid @RequestParam(value = "string_group", required = false) Integer stringGroup,@ApiParam(value = "Boolean in group parameters" ) @RequestHeader(value="boolean_group", required=false) Boolean booleanGroup,@ApiParam(value = "Integer in group parameters") @Valid @RequestParam(value = "int64_group", required = false) Long int64Group);
 
 
+    /**
+     * 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") })
@@ -149,6 +259,13 @@ public interface FakeApi {
     ResponseEntity<Void> testInlineAdditionalProperties(@ApiParam(value = "request body" ,required=true )  @Valid @RequestBody Map<String, String> param);
 
 
+    /**
+     * 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") })
@@ -158,6 +275,17 @@ public interface FakeApi {
     ResponseEntity<Void> testJsonFormData(@ApiParam(value = "field1", required=true) @RequestParam(value="param", required=true)  String param,@ApiParam(value = "field2", required=true) @RequestParam(value="param2", required=true)  String param2);
 
 
+    /**
+     * 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") })
@@ -166,6 +294,14 @@ public interface FakeApi {
     ResponseEntity<Void> testQueryParameterCollectionFormat(@NotNull @ApiParam(value = "", required = true) @Valid @RequestParam(value = "pipe", required = true) List<String> pipe,@NotNull @ApiParam(value = "", required = true) @Valid @RequestParam(value = "ioutil", required = true) List<String> ioutil,@NotNull @ApiParam(value = "", required = true) @Valid @RequestParam(value = "http", required = true) List<String> http,@NotNull @ApiParam(value = "", required = true) @Valid @RequestParam(value = "url", required = true) List<String> url,@NotNull @ApiParam(value = "", required = true) @Valid @RequestParam(value = "context", required = true) List<String> context);
 
 
+    /**
+     * 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/springboot-delegate/src/main/java/org/openapitools/api/FakeApiController.java

@@ -39,62 +39,213 @@ public class FakeApiController implements FakeApi {
         this.delegate = delegate;
     }
 
+    /**
+     * POST /fake/create_xml_item : creates an XmlItem
+     * this route creates an XmlItem
+     *
+     * @param xmlItem XmlItem Body (required)
+     * @return successful operation (status code 200)
+     * @see FakeApi#createXmlItem
+     */
     public ResponseEntity<Void> createXmlItem(@ApiParam(value = "XmlItem Body" ,required=true )  @Valid @RequestBody XmlItem xmlItem) {
         return delegate.createXmlItem(xmlItem);
     }
 
+    /**
+     * POST /fake/outer/boolean
+     * Test serialization of outer boolean types
+     *
+     * @param body Input boolean as post body (optional)
+     * @return Output boolean (status code 200)
+     * @see FakeApi#fakeOuterBooleanSerialize
+     */
     public ResponseEntity<Boolean> fakeOuterBooleanSerialize(@ApiParam(value = "Input boolean as post body"  )  @Valid @RequestBody Boolean body) {
         return delegate.fakeOuterBooleanSerialize(body);
     }
 
+    /**
+     * 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)
+     * @see FakeApi#fakeOuterCompositeSerialize
+     */
     public ResponseEntity<OuterComposite> fakeOuterCompositeSerialize(@ApiParam(value = "Input composite as post body"  )  @Valid @RequestBody OuterComposite body) {
         return delegate.fakeOuterCompositeSerialize(body);
     }
 
+    /**
+     * POST /fake/outer/number
+     * Test serialization of outer number types
+     *
+     * @param body Input number as post body (optional)
+     * @return Output number (status code 200)
+     * @see FakeApi#fakeOuterNumberSerialize
+     */
     public ResponseEntity<BigDecimal> fakeOuterNumberSerialize(@ApiParam(value = "Input number as post body"  )  @Valid @RequestBody BigDecimal body) {
         return delegate.fakeOuterNumberSerialize(body);
     }
 
+    /**
+     * POST /fake/outer/string
+     * Test serialization of outer string types
+     *
+     * @param body Input string as post body (optional)
+     * @return Output string (status code 200)
+     * @see FakeApi#fakeOuterStringSerialize
+     */
     public ResponseEntity<String> fakeOuterStringSerialize(@ApiParam(value = "Input string as post body"  )  @Valid @RequestBody String body) {
         return delegate.fakeOuterStringSerialize(body);
     }
 
+    /**
+     * PUT /fake/body-with-file-schema
+     * For this test, the body for this request much reference a schema named &#x60;File&#x60;.
+     *
+     * @param body  (required)
+     * @return Success (status code 200)
+     * @see FakeApi#testBodyWithFileSchema
+     */
     public ResponseEntity<Void> testBodyWithFileSchema(@ApiParam(value = "" ,required=true )  @Valid @RequestBody FileSchemaTestClass body) {
         return delegate.testBodyWithFileSchema(body);
     }
 
+    /**
+     * PUT /fake/body-with-query-params
+     *
+     * @param query  (required)
+     * @param body  (required)
+     * @return Success (status code 200)
+     * @see FakeApi#testBodyWithQueryParams
+     */
     public ResponseEntity<Void> testBodyWithQueryParams(@NotNull @ApiParam(value = "", required = true) @Valid @RequestParam(value = "query", required = true) String query,@ApiParam(value = "" ,required=true )  @Valid @RequestBody User body) {
         return delegate.testBodyWithQueryParams(query, body);
     }
 
+    /**
+     * PATCH /fake : To test \&quot;client\&quot; model
+     * To test \&quot;client\&quot; model
+     *
+     * @param body client model (required)
+     * @return successful operation (status code 200)
+     * @see FakeApi#testClientModel
+     */
     public ResponseEntity<Client> testClientModel(@ApiParam(value = "client model" ,required=true )  @Valid @RequestBody Client body) {
         return delegate.testClientModel(body);
     }
 
+    /**
+     * 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)
+     * @see FakeApi#testEndpointParameters
+     */
     public ResponseEntity<Void> testEndpointParameters(@ApiParam(value = "None", required=true) @RequestParam(value="number", required=true)  BigDecimal number,@ApiParam(value = "None", required=true) @RequestParam(value="double", required=true)  Double _double,@ApiParam(value = "None", required=true) @RequestParam(value="pattern_without_delimiter", required=true)  String patternWithoutDelimiter,@ApiParam(value = "None", required=true) @RequestParam(value="byte", required=true)  byte[] _byte,@ApiParam(value = "None") @RequestParam(value="integer", required=false)  Integer integer,@ApiParam(value = "None") @RequestParam(value="int32", required=false)  Integer int32,@ApiParam(value = "None") @RequestParam(value="int64", required=false)  Long int64,@ApiParam(value = "None") @RequestParam(value="float", required=false)  Float _float,@ApiParam(value = "None") @RequestParam(value="string", required=false)  String string,@ApiParam(value = "file detail") @Valid @RequestPart("file") MultipartFile binary,@ApiParam(value = "None") @RequestParam(value="date", required=false)  LocalDate date,@ApiParam(value = "None") @RequestParam(value="dateTime", required=false)  OffsetDateTime dateTime,@ApiParam(value = "None") @RequestParam(value="password", required=false)  String password,@ApiParam(value = "None") @RequestParam(value="callback", required=false)  String paramCallback) {
         return delegate.testEndpointParameters(number, _double, patternWithoutDelimiter, _byte, integer, int32, int64, _float, string, binary, date, dateTime, password, paramCallback);
     }
 
+    /**
+     * GET /fake : To test enum parameters
+     * To test enum parameters
+     *
+     * @param enumHeaderStringArray Header parameter enum test (string array) (optional, default to new ArrayList&lt;String&gt;())
+     * @param enumHeaderString Header parameter enum test (string) (optional, default to -efg)
+     * @param enumQueryStringArray Query parameter enum test (string array) (optional, default to new ArrayList&lt;String&gt;())
+     * @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)
+     * @see FakeApi#testEnumParameters
+     */
     public ResponseEntity<Void> testEnumParameters(@ApiParam(value = "Header parameter enum test (string array)" , allowableValues=">, $") @RequestHeader(value="enum_header_string_array", required=false) List<String> enumHeaderStringArray,@ApiParam(value = "Header parameter enum test (string)" , allowableValues="_abc, -efg, (xyz)", defaultValue="-efg") @RequestHeader(value="enum_header_string", required=false) String enumHeaderString,@ApiParam(value = "Query parameter enum test (string array)", allowableValues = ">, $") @Valid @RequestParam(value = "enum_query_string_array", required = false) List<String> enumQueryStringArray,@ApiParam(value = "Query parameter enum test (string)", allowableValues = "_abc, -efg, (xyz)", defaultValue = "-efg") @Valid @RequestParam(value = "enum_query_string", required = false, defaultValue="-efg") String enumQueryString,@ApiParam(value = "Query parameter enum test (double)", allowableValues = "1, -2") @Valid @RequestParam(value = "enum_query_integer", required = false) Integer enumQueryInteger,@ApiParam(value = "Query parameter enum test (double)", allowableValues = "1.1, -1.2") @Valid @RequestParam(value = "enum_query_double", required = false) Double enumQueryDouble,@ApiParam(value = "Form parameter enum test (string array)", allowableValues=">, $") @RequestParam(value="enum_form_string_array", required=false)  List<String> enumFormStringArray,@ApiParam(value = "Form parameter enum test (string)", allowableValues="_abc, -efg, (xyz)", defaultValue="-efg") @RequestParam(value="enum_form_string", required=false)  String enumFormString) {
         return delegate.testEnumParameters(enumHeaderStringArray, enumHeaderString, enumQueryStringArray, enumQueryString, enumQueryInteger, enumQueryDouble, enumFormStringArray, enumFormString);
     }
 
+    /**
+     * 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)
+     * @see FakeApi#testGroupParameters
+     */
     public ResponseEntity<Void> testGroupParameters(@NotNull @ApiParam(value = "Required String in group parameters", required = true) @Valid @RequestParam(value = "required_string_group", required = true) Integer requiredStringGroup,@ApiParam(value = "Required Boolean in group parameters" ,required=true) @RequestHeader(value="required_boolean_group", required=true) Boolean requiredBooleanGroup,@NotNull @ApiParam(value = "Required Integer in group parameters", required = true) @Valid @RequestParam(value = "required_int64_group", required = true) Long requiredInt64Group,@ApiParam(value = "String in group parameters") @Valid @RequestParam(value = "string_group", required = false) Integer stringGroup,@ApiParam(value = "Boolean in group parameters" ) @RequestHeader(value="boolean_group", required=false) Boolean booleanGroup,@ApiParam(value = "Integer in group parameters") @Valid @RequestParam(value = "int64_group", required = false) Long int64Group) {
         return delegate.testGroupParameters(requiredStringGroup, requiredBooleanGroup, requiredInt64Group, stringGroup, booleanGroup, int64Group);
     }
 
+    /**
+     * POST /fake/inline-additionalProperties : test inline additionalProperties
+     *
+     * @param param request body (required)
+     * @return successful operation (status code 200)
+     * @see FakeApi#testInlineAdditionalProperties
+     */
     public ResponseEntity<Void> testInlineAdditionalProperties(@ApiParam(value = "request body" ,required=true )  @Valid @RequestBody Map<String, String> param) {
         return delegate.testInlineAdditionalProperties(param);
     }
 
+    /**
+     * GET /fake/jsonFormData : test json serialization of form data
+     *
+     * @param param field1 (required)
+     * @param param2 field2 (required)
+     * @return successful operation (status code 200)
+     * @see FakeApi#testJsonFormData
+     */
     public ResponseEntity<Void> testJsonFormData(@ApiParam(value = "field1", required=true) @RequestParam(value="param", required=true)  String param,@ApiParam(value = "field2", required=true) @RequestParam(value="param2", required=true)  String param2) {
         return delegate.testJsonFormData(param, param2);
     }
 
+    /**
+     * 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)
+     * @see FakeApi#testQueryParameterCollectionFormat
+     */
     public ResponseEntity<Void> testQueryParameterCollectionFormat(@NotNull @ApiParam(value = "", required = true) @Valid @RequestParam(value = "pipe", required = true) List<String> pipe,@NotNull @ApiParam(value = "", required = true) @Valid @RequestParam(value = "ioutil", required = true) List<String> ioutil,@NotNull @ApiParam(value = "", required = true) @Valid @RequestParam(value = "http", required = true) List<String> http,@NotNull @ApiParam(value = "", required = true) @Valid @RequestParam(value = "url", required = true) List<String> url,@NotNull @ApiParam(value = "", required = true) @Valid @RequestParam(value = "context", required = true) List<String> context) {
         return delegate.testQueryParameterCollectionFormat(pipe, ioutil, http, url, context);
     }
 
+    /**
+     * 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)
+     * @see FakeApi#uploadFileWithRequiredFile
+     */
     public ResponseEntity<ModelApiResponse> uploadFileWithRequiredFile(@ApiParam(value = "ID of pet to update",required=true) @PathVariable("petId") Long petId,@ApiParam(value = "file detail") @Valid @RequestPart("file") MultipartFile requiredFile,@ApiParam(value = "Additional data to pass to server") @RequestParam(value="additionalMetadata", required=false)  String additionalMetadata) {
         return delegate.uploadFileWithRequiredFile(petId, requiredFile, additionalMetadata);
     }

samples/server/petstore/springboot-delegate/src/main/java/org/openapitools/api/FakeApiDelegate.java

@@ -26,47 +26,106 @@ import java.util.Map;
 public interface FakeApiDelegate {
 
     /**
+     * POST /fake/create_xml_item : creates an XmlItem
+     * this route creates an XmlItem
+     *
+     * @param xmlItem XmlItem Body (required)
+     * @return successful operation (status code 200)
      * @see FakeApi#createXmlItem
      */
     ResponseEntity<Void> createXmlItem(XmlItem xmlItem);
 
     /**
+     * POST /fake/outer/boolean
+     * Test serialization of outer boolean types
+     *
+     * @param body Input boolean as post body (optional)
+     * @return Output boolean (status code 200)
      * @see FakeApi#fakeOuterBooleanSerialize
      */
     ResponseEntity<Boolean> fakeOuterBooleanSerialize(Boolean body);
 
     /**
+     * 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)
      * @see FakeApi#fakeOuterCompositeSerialize
      */
     ResponseEntity<OuterComposite> fakeOuterCompositeSerialize(OuterComposite body);
 
     /**
+     * POST /fake/outer/number
+     * Test serialization of outer number types
+     *
+     * @param body Input number as post body (optional)
+     * @return Output number (status code 200)
      * @see FakeApi#fakeOuterNumberSerialize
      */
     ResponseEntity<BigDecimal> fakeOuterNumberSerialize(BigDecimal body);
 
     /**
+     * POST /fake/outer/string
+     * Test serialization of outer string types
+     *
+     * @param body Input string as post body (optional)
+     * @return Output string (status code 200)
      * @see FakeApi#fakeOuterStringSerialize
      */
     ResponseEntity<String> fakeOuterStringSerialize(String body);
 
     /**
+     * PUT /fake/body-with-file-schema
+     * For this test, the body for this request much reference a schema named &#x60;File&#x60;.
+     *
+     * @param body  (required)
+     * @return Success (status code 200)
      * @see FakeApi#testBodyWithFileSchema
      */
     ResponseEntity<Void> testBodyWithFileSchema(FileSchemaTestClass body);
 
     /**
+     * PUT /fake/body-with-query-params
+     *
+     * @param query  (required)
+     * @param body  (required)
+     * @return Success (status code 200)
      * @see FakeApi#testBodyWithQueryParams
      */
     ResponseEntity<Void> testBodyWithQueryParams(String query,
         User body);
 
     /**
+     * PATCH /fake : To test \&quot;client\&quot; model
+     * To test \&quot;client\&quot; model
+     *
+     * @param body client model (required)
+     * @return successful operation (status code 200)
      * @see FakeApi#testClientModel
      */
     ResponseEntity<Client> testClientModel(Client body);
 
     /**
+     * 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)
      * @see FakeApi#testEndpointParameters
      */
     ResponseEntity<Void> testEndpointParameters(BigDecimal number,
@@ -85,6 +144,19 @@ public interface FakeApiDelegate {
         String paramCallback);
 
     /**
+     * GET /fake : To test enum parameters
+     * To test enum parameters
+     *
+     * @param enumHeaderStringArray Header parameter enum test (string array) (optional, default to new ArrayList&lt;String&gt;())
+     * @param enumHeaderString Header parameter enum test (string) (optional, default to -efg)
+     * @param enumQueryStringArray Query parameter enum test (string array) (optional, default to new ArrayList&lt;String&gt;())
+     * @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)
      * @see FakeApi#testEnumParameters
      */
     ResponseEntity<Void> testEnumParameters(List<String> enumHeaderStringArray,
@@ -97,6 +169,16 @@ public interface FakeApiDelegate {
         String enumFormString);
 
     /**
+     * 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)
      * @see FakeApi#testGroupParameters
      */
     ResponseEntity<Void> testGroupParameters(Integer requiredStringGroup,
@@ -107,17 +189,35 @@ public interface FakeApiDelegate {
         Long int64Group);
 
     /**
+     * POST /fake/inline-additionalProperties : test inline additionalProperties
+     *
+     * @param param request body (required)
+     * @return successful operation (status code 200)
      * @see FakeApi#testInlineAdditionalProperties
      */
     ResponseEntity<Void> testInlineAdditionalProperties(Map<String, String> param);
 
     /**
+     * GET /fake/jsonFormData : test json serialization of form data
+     *
+     * @param param field1 (required)
+     * @param param2 field2 (required)
+     * @return successful operation (status code 200)
      * @see FakeApi#testJsonFormData
      */
     ResponseEntity<Void> testJsonFormData(String param,
         String param2);
 
     /**
+     * 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)
      * @see FakeApi#testQueryParameterCollectionFormat
      */
     ResponseEntity<Void> testQueryParameterCollectionFormat(List<String> pipe,
@@ -127,6 +227,12 @@ public interface FakeApiDelegate {
         List<String> context);
 
     /**
+     * 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)
      * @see FakeApi#uploadFileWithRequiredFile
      */
     ResponseEntity<ModelApiResponse> uploadFileWithRequiredFile(Long petId,

samples/server/petstore/springboot-delegate/src/main/java/org/openapitools/api/FakeClassnameTestApi.java

@@ -27,6 +27,13 @@ import java.util.Map;
 @Api(value = "fake_classname_test", description = "the fake_classname_test API")
 public interface FakeClassnameTestApi {
 
+    /**
+     * 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/springboot-delegate/src/main/java/org/openapitools/api/FakeClassnameTestApiController.java

@@ -29,6 +29,14 @@ public class FakeClassnameTestApiController implements FakeClassnameTestApi {
         this.delegate = delegate;
     }
 
+    /**
+     * 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)
+     * @see FakeClassnameTestApi#testClassname
+     */
     public ResponseEntity<Client> testClassname(@ApiParam(value = "client model" ,required=true )  @Valid @RequestBody Client body) {
         return delegate.testClassname(body);
     }

samples/server/petstore/springboot-delegate/src/main/java/org/openapitools/api/FakeClassnameTestApiDelegate.java

@@ -16,6 +16,11 @@ import java.util.Map;
 public interface FakeClassnameTestApiDelegate {
 
     /**
+     * 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)
      * @see FakeClassnameTestApi#testClassname
      */
     ResponseEntity<Client> testClassname(Client body);

samples/server/petstore/springboot-delegate/src/main/java/org/openapitools/api/PetApi.java

@@ -29,6 +29,13 @@ import java.util.Map;
 @Api(value = "pet", description = "the pet API")
 public interface PetApi {
 
+    /**
+     * 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"),
@@ -44,6 +51,14 @@ public interface PetApi {
     ResponseEntity<Void> addPet(@ApiParam(value = "Pet object that needs to be added to the store" ,required=true )  @Valid @RequestBody Pet body);
 
 
+    /**
+     * 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"),
@@ -58,6 +73,14 @@ public interface PetApi {
     ResponseEntity<Void> deletePet(@ApiParam(value = "Pet id to delete",required=true) @PathVariable("petId") Long petId,@ApiParam(value = "" ) @RequestHeader(value="api_key", required=false) String apiKey);
 
 
+    /**
+     * 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"),
@@ -73,6 +96,15 @@ public interface PetApi {
     ResponseEntity<List<Pet>> findPetsByStatus(@NotNull @ApiParam(value = "Status values that need to be considered for filter", required = true, allowableValues = "available, pending, sold") @Valid @RequestParam(value = "status", required = true) List<String> status);
 
 
+    /**
+     * 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"),
@@ -88,6 +120,15 @@ public interface PetApi {
     ResponseEntity<List<Pet>> findPetsByTags(@NotNull @ApiParam(value = "Tags to filter by", required = true) @Valid @RequestParam(value = "tags", required = true) List<String> tags);
 
 
+    /**
+     * 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", })
@@ -101,6 +142,15 @@ public interface PetApi {
     ResponseEntity<Pet> getPetById(@ApiParam(value = "ID of pet to return",required=true) @PathVariable("petId") Long petId);
 
 
+    /**
+     * 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"),
@@ -118,6 +168,14 @@ public interface PetApi {
     ResponseEntity<Void> updatePet(@ApiParam(value = "Pet object that needs to be added to the store" ,required=true )  @Valid @RequestBody Pet body);
 
 
+    /**
+     * 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"),
@@ -132,6 +190,14 @@ public interface PetApi {
     ResponseEntity<Void> updatePetWithForm(@ApiParam(value = "ID of pet that needs to be updated",required=true) @PathVariable("petId") Long petId,@ApiParam(value = "Updated name of the pet") @RequestParam(value="name", required=false)  String name,@ApiParam(value = "Updated status of the pet") @RequestParam(value="status", required=false)  String status);
 
 
+    /**
+     * 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/springboot-delegate/src/main/java/org/openapitools/api/PetApiController.java

@@ -31,34 +31,108 @@ public class PetApiController implements PetApi {
         this.delegate = delegate;
     }
 
+    /**
+     * 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)
+     * @see PetApi#addPet
+     */
     public ResponseEntity<Void> addPet(@ApiParam(value = "Pet object that needs to be added to the store" ,required=true )  @Valid @RequestBody Pet body) {
         return delegate.addPet(body);
     }
 
+    /**
+     * 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)
+     * @see PetApi#deletePet
+     */
     public ResponseEntity<Void> deletePet(@ApiParam(value = "Pet id to delete",required=true) @PathVariable("petId") Long petId,@ApiParam(value = "" ) @RequestHeader(value="api_key", required=false) String apiKey) {
         return delegate.deletePet(petId, apiKey);
     }
 
+    /**
+     * 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)
+     * @see PetApi#findPetsByStatus
+     */
     public ResponseEntity<List<Pet>> findPetsByStatus(@NotNull @ApiParam(value = "Status values that need to be considered for filter", required = true, allowableValues = "available, pending, sold") @Valid @RequestParam(value = "status", required = true) List<String> status) {
         return delegate.findPetsByStatus(status);
     }
 
+    /**
+     * 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
+     * @see PetApi#findPetsByTags
+     */
     public ResponseEntity<List<Pet>> findPetsByTags(@NotNull @ApiParam(value = "Tags to filter by", required = true) @Valid @RequestParam(value = "tags", required = true) List<String> tags) {
         return delegate.findPetsByTags(tags);
     }
 
+    /**
+     * 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)
+     * @see PetApi#getPetById
+     */
     public ResponseEntity<Pet> getPetById(@ApiParam(value = "ID of pet to return",required=true) @PathVariable("petId") Long petId) {
         return delegate.getPetById(petId);
     }
 
+    /**
+     * 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)
+     * @see PetApi#updatePet
+     */
     public ResponseEntity<Void> updatePet(@ApiParam(value = "Pet object that needs to be added to the store" ,required=true )  @Valid @RequestBody Pet body) {
         return delegate.updatePet(body);
     }
 
+    /**
+     * 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)
+     * @see PetApi#updatePetWithForm
+     */
     public ResponseEntity<Void> updatePetWithForm(@ApiParam(value = "ID of pet that needs to be updated",required=true) @PathVariable("petId") Long petId,@ApiParam(value = "Updated name of the pet") @RequestParam(value="name", required=false)  String name,@ApiParam(value = "Updated status of the pet") @RequestParam(value="status", required=false)  String status) {
         return delegate.updatePetWithForm(petId, name, status);
     }
 
+    /**
+     * 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)
+     * @see PetApi#uploadFile
+     */
     public ResponseEntity<ModelApiResponse> uploadFile(@ApiParam(value = "ID of pet to update",required=true) @PathVariable("petId") Long petId,@ApiParam(value = "Additional data to pass to server") @RequestParam(value="additionalMetadata", required=false)  String additionalMetadata,@ApiParam(value = "file detail") @Valid @RequestPart("file") MultipartFile file) {
         return delegate.uploadFile(petId, additionalMetadata, file);
     }

samples/server/petstore/springboot-delegate/src/main/java/org/openapitools/api/PetApiDelegate.java

@@ -18,37 +18,81 @@ import java.util.Map;
 public interface PetApiDelegate {
 
     /**
+     * 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)
      * @see PetApi#addPet
      */
     ResponseEntity<Void> addPet(Pet body);
 
     /**
+     * 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)
      * @see PetApi#deletePet
      */
     ResponseEntity<Void> deletePet(Long petId,
         String apiKey);
 
     /**
+     * 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)
      * @see PetApi#findPetsByStatus
      */
     ResponseEntity<List<Pet>> findPetsByStatus(List<String> status);
 
     /**
+     * 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
      * @see PetApi#findPetsByTags
      */
     ResponseEntity<List<Pet>> findPetsByTags(List<String> tags);
 
     /**
+     * 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)
      * @see PetApi#getPetById
      */
     ResponseEntity<Pet> getPetById(Long petId);
 
     /**
+     * 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)
      * @see PetApi#updatePet
      */
     ResponseEntity<Void> updatePet(Pet body);
 
     /**
+     * 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)
      * @see PetApi#updatePetWithForm
      */
     ResponseEntity<Void> updatePetWithForm(Long petId,
@@ -56,6 +100,12 @@ public interface PetApiDelegate {
         String status);
 
     /**
+     * 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)
      * @see PetApi#uploadFile
      */
     ResponseEntity<ModelApiResponse> uploadFile(Long petId,

samples/server/petstore/springboot-delegate/src/main/java/org/openapitools/api/StoreApi.java

@@ -28,6 +28,14 @@ import java.util.Map;
 @Api(value = "store", description = "the store API")
 public interface StoreApi {
 
+    /**
+     * 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"),
@@ -37,6 +45,12 @@ public interface StoreApi {
     ResponseEntity<Void> deleteOrder(@ApiParam(value = "ID of the order that needs to be deleted",required=true) @PathVariable("order_id") String orderId);
 
 
+    /**
+     * 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", })
@@ -48,6 +62,15 @@ public interface StoreApi {
     ResponseEntity<Map<String, Integer>> getInventory();
 
 
+    /**
+     * 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),
@@ -59,6 +82,13 @@ public interface StoreApi {
     ResponseEntity<Order> getOrderById(@Min(1L) @Max(5L) @ApiParam(value = "ID of pet that needs to be fetched",required=true) @PathVariable("order_id") Long orderId);
 
 
+    /**
+     * 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/springboot-delegate/src/main/java/org/openapitools/api/StoreApiController.java

@@ -30,18 +30,52 @@ public class StoreApiController implements StoreApi {
         this.delegate = delegate;
     }
 
+    /**
+     * 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)
+     * @see StoreApi#deleteOrder
+     */
     public ResponseEntity<Void> deleteOrder(@ApiParam(value = "ID of the order that needs to be deleted",required=true) @PathVariable("order_id") String orderId) {
         return delegate.deleteOrder(orderId);
     }
 
+    /**
+     * GET /store/inventory : Returns pet inventories by status
+     * Returns a map of status codes to quantities
+     *
+     * @return successful operation (status code 200)
+     * @see StoreApi#getInventory
+     */
     public ResponseEntity<Map<String, Integer>> getInventory() {
         return delegate.getInventory();
     }
 
+    /**
+     * 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)
+     * @see StoreApi#getOrderById
+     */
     public ResponseEntity<Order> getOrderById(@Min(1L) @Max(5L) @ApiParam(value = "ID of pet that needs to be fetched",required=true) @PathVariable("order_id") Long orderId) {
         return delegate.getOrderById(orderId);
     }
 
+    /**
+     * 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)
+     * @see StoreApi#placeOrder
+     */
     public ResponseEntity<Order> placeOrder(@ApiParam(value = "order placed for purchasing the pet" ,required=true )  @Valid @RequestBody Order body) {
         return delegate.placeOrder(body);
     }

samples/server/petstore/springboot-delegate/src/main/java/org/openapitools/api/StoreApiDelegate.java

@@ -17,21 +17,43 @@ import java.util.Map;
 public interface StoreApiDelegate {
 
     /**
+     * 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)
      * @see StoreApi#deleteOrder
      */
     ResponseEntity<Void> deleteOrder(String orderId);
 
     /**
+     * GET /store/inventory : Returns pet inventories by status
+     * Returns a map of status codes to quantities
+     *
+     * @return successful operation (status code 200)
      * @see StoreApi#getInventory
      */
     ResponseEntity<Map<String, Integer>> getInventory();
 
     /**
+     * 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)
      * @see StoreApi#getOrderById
      */
     ResponseEntity<Order> getOrderById(Long orderId);
 
     /**
+     * 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)
      * @see StoreApi#placeOrder
      */
     ResponseEntity<Order> placeOrder(Order body);

samples/server/petstore/springboot-delegate/src/main/java/org/openapitools/api/UserApi.java

@@ -28,6 +28,13 @@ import java.util.Map;
 @Api(value = "user", description = "the user API")
 public interface UserApi {
 
+    /**
+     * 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") })
@@ -36,6 +43,12 @@ public interface UserApi {
     ResponseEntity<Void> createUser(@ApiParam(value = "Created user object" ,required=true )  @Valid @RequestBody User body);
 
 
+    /**
+     * 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") })
@@ -44,6 +57,12 @@ public interface UserApi {
     ResponseEntity<Void> createUsersWithArrayInput(@ApiParam(value = "List of user object" ,required=true )  @Valid @RequestBody List<User> body);
 
 
+    /**
+     * 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") })
@@ -52,6 +71,14 @@ public interface UserApi {
     ResponseEntity<Void> createUsersWithListInput(@ApiParam(value = "List of user object" ,required=true )  @Valid @RequestBody List<User> body);
 
 
+    /**
+     * 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"),
@@ -61,6 +88,14 @@ public interface UserApi {
     ResponseEntity<Void> deleteUser(@ApiParam(value = "The name that needs to be deleted",required=true) @PathVariable("username") String username);
 
 
+    /**
+     * 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),
@@ -72,6 +107,14 @@ public interface UserApi {
     ResponseEntity<User> getUserByName(@ApiParam(value = "The name that needs to be fetched. Use user1 for testing.",required=true) @PathVariable("username") String username);
 
 
+    /**
+     * 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),
@@ -82,6 +125,11 @@ public interface UserApi {
     ResponseEntity<String> loginUser(@NotNull @ApiParam(value = "The user name for login", required = true) @Valid @RequestParam(value = "username", required = true) String username,@NotNull @ApiParam(value = "The password for login in clear text", required = true) @Valid @RequestParam(value = "password", required = true) String password);
 
 
+    /**
+     * 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") })
@@ -90,6 +138,15 @@ public interface UserApi {
     ResponseEntity<Void> logoutUser();
 
 
+    /**
+     * 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"),

samples/server/petstore/springboot-delegate/src/main/java/org/openapitools/api/UserApiController.java

@@ -30,34 +30,99 @@ public class UserApiController implements UserApi {
         this.delegate = delegate;
     }
 
+    /**
+     * 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)
+     * @see UserApi#createUser
+     */
     public ResponseEntity<Void> createUser(@ApiParam(value = "Created user object" ,required=true )  @Valid @RequestBody User body) {
         return delegate.createUser(body);
     }
 
+    /**
+     * POST /user/createWithArray : Creates list of users with given input array
+     *
+     * @param body List of user object (required)
+     * @return successful operation (status code 200)
+     * @see UserApi#createUsersWithArrayInput
+     */
     public ResponseEntity<Void> createUsersWithArrayInput(@ApiParam(value = "List of user object" ,required=true )  @Valid @RequestBody List<User> body) {
         return delegate.createUsersWithArrayInput(body);
     }
 
+    /**
+     * POST /user/createWithList : Creates list of users with given input array
+     *
+     * @param body List of user object (required)
+     * @return successful operation (status code 200)
+     * @see UserApi#createUsersWithListInput
+     */
     public ResponseEntity<Void> createUsersWithListInput(@ApiParam(value = "List of user object" ,required=true )  @Valid @RequestBody List<User> body) {
         return delegate.createUsersWithListInput(body);
     }
 
+    /**
+     * 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)
+     * @see UserApi#deleteUser
+     */
     public ResponseEntity<Void> deleteUser(@ApiParam(value = "The name that needs to be deleted",required=true) @PathVariable("username") String username) {
         return delegate.deleteUser(username);
     }
 
+    /**
+     * 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)
+     * @see UserApi#getUserByName
+     */
     public ResponseEntity<User> getUserByName(@ApiParam(value = "The name that needs to be fetched. Use user1 for testing.",required=true) @PathVariable("username") String username) {
         return delegate.getUserByName(username);
     }
 
+    /**
+     * 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)
+     * @see UserApi#loginUser
+     */
     public ResponseEntity<String> loginUser(@NotNull @ApiParam(value = "The user name for login", required = true) @Valid @RequestParam(value = "username", required = true) String username,@NotNull @ApiParam(value = "The password for login in clear text", required = true) @Valid @RequestParam(value = "password", required = true) String password) {
         return delegate.loginUser(username, password);
     }
 
+    /**
+     * GET /user/logout : Logs out current logged in user session
+     *
+     * @return successful operation (status code 200)
+     * @see UserApi#logoutUser
+     */
     public ResponseEntity<Void> logoutUser() {
         return delegate.logoutUser();
     }
 
+    /**
+     * 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)
+     * @see UserApi#updateUser
+     */
     public ResponseEntity<Void> updateUser(@ApiParam(value = "name that need to be deleted",required=true) @PathVariable("username") String username,@ApiParam(value = "Updated user object" ,required=true )  @Valid @RequestBody User body) {
         return delegate.updateUser(username, body);
     }

samples/server/petstore/springboot-delegate/src/main/java/org/openapitools/api/UserApiDelegate.java

@@ -17,42 +17,83 @@ import java.util.Map;
 public interface UserApiDelegate {
 
     /**
+     * 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)
      * @see UserApi#createUser
      */
     ResponseEntity<Void> createUser(User body);
 
     /**
+     * POST /user/createWithArray : Creates list of users with given input array
+     *
+     * @param body List of user object (required)
+     * @return successful operation (status code 200)
      * @see UserApi#createUsersWithArrayInput
      */
     ResponseEntity<Void> createUsersWithArrayInput(List<User> body);
 
     /**
+     * POST /user/createWithList : Creates list of users with given input array
+     *
+     * @param body List of user object (required)
+     * @return successful operation (status code 200)
      * @see UserApi#createUsersWithListInput
      */
     ResponseEntity<Void> createUsersWithListInput(List<User> body);
 
     /**
+     * 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)
      * @see UserApi#deleteUser
      */
     ResponseEntity<Void> deleteUser(String username);
 
     /**
+     * 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)
      * @see UserApi#getUserByName
      */
     ResponseEntity<User> getUserByName(String username);
 
     /**
+     * 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)
      * @see UserApi#loginUser
      */
     ResponseEntity<String> loginUser(String username,
         String password);
 
     /**
+     * GET /user/logout : Logs out current logged in user session
+     *
+     * @return successful operation (status code 200)
      * @see UserApi#logoutUser
      */
     ResponseEntity<Void> logoutUser();
 
     /**
+     * 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)
      * @see UserApi#updateUser
      */
     ResponseEntity<Void> updateUser(String username,

samples/server/petstore/springboot-implicitHeaders/src/main/java/org/openapitools/api/AnotherFakeApi.java

@@ -35,6 +35,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/springboot-implicitHeaders/src/main/java/org/openapitools/api/FakeApi.java

@@ -45,6 +45,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") })
@@ -59,6 +66,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) })
@@ -73,6 +87,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) })
@@ -96,6 +117,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) })
@@ -110,6 +138,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) })
@@ -124,6 +159,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") })
@@ -138,6 +180,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") })
@@ -152,6 +201,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) })
@@ -176,6 +232,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", })
@@ -193,6 +270,19 @@ public interface FakeApi {
     }
 
 
+    /**
+     * GET /fake : To test enum parameters
+     * To test enum parameters
+     *
+     * @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"),
@@ -210,6 +300,16 @@ 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 requiredInt64Group Required Integer in group parameters (required)
+     * @param stringGroup String 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") })
@@ -225,6 +325,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") })
@@ -239,6 +345,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") })
@@ -253,6 +366,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") })
@@ -266,6 +390,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/springboot-implicitHeaders/src/main/java/org/openapitools/api/FakeClassnameTestApi.java

@@ -35,6 +35,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/springboot-implicitHeaders/src/main/java/org/openapitools/api/PetApi.java

@@ -37,6 +37,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"),
@@ -57,6 +64,13 @@ public interface PetApi {
     }
 
 
+    /**
+     * DELETE /pet/{petId} : Deletes a pet
+     *
+     * @param petId Pet id to delete (required)
+     * @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"),
@@ -77,6 +91,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"),
@@ -111,6 +133,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"),
@@ -145,6 +176,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", })
@@ -177,6 +217,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"),
@@ -199,6 +248,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"),
@@ -218,6 +275,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/springboot-implicitHeaders/src/main/java/org/openapitools/api/StoreApi.java

@@ -36,6 +36,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"),
@@ -50,6 +58,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", })
@@ -66,6 +80,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),
@@ -96,6 +119,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/springboot-implicitHeaders/src/main/java/org/openapitools/api/UserApi.java

@@ -36,6 +36,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") })
@@ -49,6 +56,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") })
@@ -62,6 +75,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") })
@@ -75,6 +94,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"),
@@ -89,6 +116,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),
@@ -119,6 +154,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),
@@ -134,6 +177,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") })
@@ -147,6 +195,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"),

samples/server/petstore/springboot-reactive/src/main/java/org/openapitools/api/AnotherFakeApi.java

@@ -34,6 +34,13 @@ public interface AnotherFakeApi {
         return new AnotherFakeApiDelegate() {};
     }
 
+    /**
+     * 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/springboot-reactive/src/main/java/org/openapitools/api/AnotherFakeApiDelegate.java

@@ -27,6 +27,11 @@ public interface AnotherFakeApiDelegate {
     }
 
     /**
+     * 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)
      * @see AnotherFakeApi#call123testSpecialTags
      */
     default Mono<ResponseEntity<Client>> call123testSpecialTags(Mono<Client> body,

samples/server/petstore/springboot-reactive/src/main/java/org/openapitools/api/FakeApi.java

@@ -44,6 +44,13 @@ public interface FakeApi {
         return new FakeApiDelegate() {};
     }
 
+    /**
+     * 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") })
@@ -55,6 +62,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) })
@@ -66,6 +80,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) })
@@ -77,6 +98,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) })
@@ -88,6 +116,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) })
@@ -99,6 +134,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") })
@@ -110,6 +152,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") })
@@ -121,6 +170,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) })
@@ -133,6 +189,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", })
@@ -147,6 +224,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"),
@@ -159,6 +251,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") })
@@ -169,6 +273,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") })
@@ -180,6 +290,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") })
@@ -191,6 +308,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") })
@@ -201,6 +329,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/springboot-reactive/src/main/java/org/openapitools/api/FakeApiDelegate.java

@@ -37,6 +37,11 @@ public interface FakeApiDelegate {
     }
 
     /**
+     * POST /fake/create_xml_item : creates an XmlItem
+     * this route creates an XmlItem
+     *
+     * @param xmlItem XmlItem Body (required)
+     * @return successful operation (status code 200)
      * @see FakeApi#createXmlItem
      */
     default Mono<ResponseEntity<Void>> createXmlItem(Mono<XmlItem> xmlItem,
@@ -48,6 +53,11 @@ public interface FakeApiDelegate {
     }
 
     /**
+     * POST /fake/outer/boolean
+     * Test serialization of outer boolean types
+     *
+     * @param body Input boolean as post body (optional)
+     * @return Output boolean (status code 200)
      * @see FakeApi#fakeOuterBooleanSerialize
      */
     default Mono<ResponseEntity<Boolean>> fakeOuterBooleanSerialize(Mono<Boolean> body,
@@ -59,6 +69,11 @@ public interface FakeApiDelegate {
     }
 
     /**
+     * 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)
      * @see FakeApi#fakeOuterCompositeSerialize
      */
     default Mono<ResponseEntity<OuterComposite>> fakeOuterCompositeSerialize(Mono<OuterComposite> body,
@@ -77,6 +92,11 @@ public interface FakeApiDelegate {
     }
 
     /**
+     * POST /fake/outer/number
+     * Test serialization of outer number types
+     *
+     * @param body Input number as post body (optional)
+     * @return Output number (status code 200)
      * @see FakeApi#fakeOuterNumberSerialize
      */
     default Mono<ResponseEntity<BigDecimal>> fakeOuterNumberSerialize(Mono<BigDecimal> body,
@@ -88,6 +108,11 @@ public interface FakeApiDelegate {
     }
 
     /**
+     * POST /fake/outer/string
+     * Test serialization of outer string types
+     *
+     * @param body Input string as post body (optional)
+     * @return Output string (status code 200)
      * @see FakeApi#fakeOuterStringSerialize
      */
     default Mono<ResponseEntity<String>> fakeOuterStringSerialize(Mono<String> body,
@@ -99,6 +124,11 @@ public interface FakeApiDelegate {
     }
 
     /**
+     * PUT /fake/body-with-file-schema
+     * For this test, the body for this request much reference a schema named &#x60;File&#x60;.
+     *
+     * @param body  (required)
+     * @return Success (status code 200)
      * @see FakeApi#testBodyWithFileSchema
      */
     default Mono<ResponseEntity<Void>> testBodyWithFileSchema(Mono<FileSchemaTestClass> body,
@@ -110,6 +140,11 @@ public interface FakeApiDelegate {
     }
 
     /**
+     * PUT /fake/body-with-query-params
+     *
+     * @param query  (required)
+     * @param body  (required)
+     * @return Success (status code 200)
      * @see FakeApi#testBodyWithQueryParams
      */
     default Mono<ResponseEntity<Void>> testBodyWithQueryParams(String query,
@@ -122,6 +157,11 @@ public interface FakeApiDelegate {
     }
 
     /**
+     * PATCH /fake : To test \&quot;client\&quot; model
+     * To test \&quot;client\&quot; model
+     *
+     * @param body client model (required)
+     * @return successful operation (status code 200)
      * @see FakeApi#testClientModel
      */
     default Mono<ResponseEntity<Client>> testClientModel(Mono<Client> body,
@@ -140,6 +180,25 @@ public interface FakeApiDelegate {
     }
 
     /**
+     * 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)
      * @see FakeApi#testEndpointParameters
      */
     default Mono<ResponseEntity<Void>> testEndpointParameters(BigDecimal number,
@@ -164,6 +223,19 @@ public interface FakeApiDelegate {
     }
 
     /**
+     * GET /fake : To test enum parameters
+     * To test enum parameters
+     *
+     * @param enumHeaderStringArray Header parameter enum test (string array) (optional, default to new ArrayList&lt;&gt;())
+     * @param enumHeaderString Header parameter enum test (string) (optional, default to -efg)
+     * @param enumQueryStringArray Query parameter enum test (string array) (optional, default to new ArrayList&lt;&gt;())
+     * @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)
      * @see FakeApi#testEnumParameters
      */
     default Mono<ResponseEntity<Void>> testEnumParameters(List<String> enumHeaderStringArray,
@@ -182,6 +254,16 @@ public interface FakeApiDelegate {
     }
 
     /**
+     * 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)
      * @see FakeApi#testGroupParameters
      */
     default Mono<ResponseEntity<Void>> testGroupParameters(Integer requiredStringGroup,
@@ -198,6 +280,10 @@ public interface FakeApiDelegate {
     }
 
     /**
+     * POST /fake/inline-additionalProperties : test inline additionalProperties
+     *
+     * @param param request body (required)
+     * @return successful operation (status code 200)
      * @see FakeApi#testInlineAdditionalProperties
      */
     default Mono<ResponseEntity<Void>> testInlineAdditionalProperties(Mono<String> param,
@@ -209,6 +295,11 @@ public interface FakeApiDelegate {
     }
 
     /**
+     * GET /fake/jsonFormData : test json serialization of form data
+     *
+     * @param param field1 (required)
+     * @param param2 field2 (required)
+     * @return successful operation (status code 200)
      * @see FakeApi#testJsonFormData
      */
     default Mono<ResponseEntity<Void>> testJsonFormData(String param,
@@ -221,6 +312,15 @@ public interface FakeApiDelegate {
     }
 
     /**
+     * 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)
      * @see FakeApi#testQueryParameterCollectionFormat
      */
     default Mono<ResponseEntity<Void>> testQueryParameterCollectionFormat(List<String> pipe,
@@ -236,6 +336,12 @@ public interface FakeApiDelegate {
     }
 
     /**
+     * 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)
      * @see FakeApi#uploadFileWithRequiredFile
      */
     default Mono<ResponseEntity<ModelApiResponse>> uploadFileWithRequiredFile(Long petId,

samples/server/petstore/springboot-reactive/src/main/java/org/openapitools/api/FakeClassnameTestApi.java

@@ -34,6 +34,13 @@ public interface FakeClassnameTestApi {
         return new FakeClassnameTestApiDelegate() {};
     }
 
+    /**
+     * 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/springboot-reactive/src/main/java/org/openapitools/api/FakeClassnameTestApiDelegate.java

@@ -27,6 +27,11 @@ public interface FakeClassnameTestApiDelegate {
     }
 
     /**
+     * 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)
      * @see FakeClassnameTestApi#testClassname
      */
     default Mono<ResponseEntity<Client>> testClassname(Mono<Client> body,

samples/server/petstore/springboot-reactive/src/main/java/org/openapitools/api/PetApi.java

@@ -36,6 +36,13 @@ public interface PetApi {
         return new PetApiDelegate() {};
     }
 
+    /**
+     * 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"),
@@ -53,6 +60,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"),
@@ -69,6 +84,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"),
@@ -86,6 +109,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"),
@@ -103,6 +135,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", })
@@ -118,6 +159,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"),
@@ -137,6 +187,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"),
@@ -153,6 +211,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/springboot-reactive/src/main/java/org/openapitools/api/PetApiDelegate.java

@@ -29,6 +29,11 @@ public interface PetApiDelegate {
     }
 
     /**
+     * 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)
      * @see PetApi#addPet
      */
     default Mono<ResponseEntity<Void>> addPet(Mono<Pet> body,
@@ -40,6 +45,12 @@ public interface PetApiDelegate {
     }
 
     /**
+     * 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)
      * @see PetApi#deletePet
      */
     default Mono<ResponseEntity<Void>> deletePet(Long petId,
@@ -52,6 +63,12 @@ public interface PetApiDelegate {
     }
 
     /**
+     * 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)
      * @see PetApi#findPetsByStatus
      */
     default Mono<ResponseEntity<Flux<Pet>>> findPetsByStatus(List<String> status,
@@ -75,6 +92,13 @@ public interface PetApiDelegate {
     }
 
     /**
+     * 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
      * @see PetApi#findPetsByTags
      */
     default Mono<ResponseEntity<Flux<Pet>>> findPetsByTags(List<String> tags,
@@ -98,6 +122,13 @@ public interface PetApiDelegate {
     }
 
     /**
+     * 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)
      * @see PetApi#getPetById
      */
     default Mono<ResponseEntity<Pet>> getPetById(Long petId,
@@ -121,6 +152,13 @@ public interface PetApiDelegate {
     }
 
     /**
+     * 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)
      * @see PetApi#updatePet
      */
     default Mono<ResponseEntity<Void>> updatePet(Mono<Pet> body,
@@ -132,6 +170,12 @@ public interface PetApiDelegate {
     }
 
     /**
+     * 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)
      * @see PetApi#updatePetWithForm
      */
     default Mono<ResponseEntity<Void>> updatePetWithForm(Long petId,
@@ -145,6 +189,12 @@ public interface PetApiDelegate {
     }
 
     /**
+     * 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)
      * @see PetApi#uploadFile
      */
     default Mono<ResponseEntity<ModelApiResponse>> uploadFile(Long petId,

samples/server/petstore/springboot-reactive/src/main/java/org/openapitools/api/StoreApi.java

@@ -35,6 +35,14 @@ public interface StoreApi {
         return new StoreApiDelegate() {};
     }
 
+    /**
+     * 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"),
@@ -46,6 +54,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", })
@@ -59,6 +73,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),
@@ -72,6 +95,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/springboot-reactive/src/main/java/org/openapitools/api/StoreApiDelegate.java

@@ -28,6 +28,12 @@ public interface StoreApiDelegate {
     }
 
     /**
+     * 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)
      * @see StoreApi#deleteOrder
      */
     default Mono<ResponseEntity<Void>> deleteOrder(String orderId,
@@ -39,6 +45,10 @@ public interface StoreApiDelegate {
     }
 
     /**
+     * GET /store/inventory : Returns pet inventories by status
+     * Returns a map of status codes to quantities
+     *
+     * @return successful operation (status code 200)
      * @see StoreApi#getInventory
      */
     default Mono<ResponseEntity<Map<String, Integer>>> getInventory(ServerWebExchange exchange) {
@@ -49,6 +59,13 @@ public interface StoreApiDelegate {
     }
 
     /**
+     * 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)
      * @see StoreApi#getOrderById
      */
     default Mono<ResponseEntity<Order>> getOrderById(Long orderId,
@@ -72,6 +89,11 @@ public interface StoreApiDelegate {
     }
 
     /**
+     * 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)
      * @see StoreApi#placeOrder
      */
     default Mono<ResponseEntity<Order>> placeOrder(Mono<Order> body,

samples/server/petstore/springboot-reactive/src/main/java/org/openapitools/api/UserApi.java

@@ -35,6 +35,13 @@ public interface UserApi {
         return new UserApiDelegate() {};
     }
 
+    /**
+     * 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") })
@@ -45,6 +52,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") })
@@ -55,6 +68,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") })
@@ -65,6 +84,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"),
@@ -76,6 +103,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),
@@ -89,6 +124,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),
@@ -101,6 +144,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") })
@@ -111,6 +159,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"),

samples/server/petstore/springboot-reactive/src/main/java/org/openapitools/api/UserApiDelegate.java

@@ -28,6 +28,11 @@ public interface UserApiDelegate {
     }
 
     /**
+     * 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)
      * @see UserApi#createUser
      */
     default Mono<ResponseEntity<Void>> createUser(Mono<User> body,
@@ -39,6 +44,10 @@ public interface UserApiDelegate {
     }
 
     /**
+     * POST /user/createWithArray : Creates list of users with given input array
+     *
+     * @param body List of user object (required)
+     * @return successful operation (status code 200)
      * @see UserApi#createUsersWithArrayInput
      */
     default Mono<ResponseEntity<Void>> createUsersWithArrayInput(Flux<User> body,
@@ -50,6 +59,10 @@ public interface UserApiDelegate {
     }
 
     /**
+     * POST /user/createWithList : Creates list of users with given input array
+     *
+     * @param body List of user object (required)
+     * @return successful operation (status code 200)
      * @see UserApi#createUsersWithListInput
      */
     default Mono<ResponseEntity<Void>> createUsersWithListInput(Flux<User> body,
@@ -61,6 +74,12 @@ public interface UserApiDelegate {
     }
 
     /**
+     * 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)
      * @see UserApi#deleteUser
      */
     default Mono<ResponseEntity<Void>> deleteUser(String username,
@@ -72,6 +91,12 @@ public interface UserApiDelegate {
     }
 
     /**
+     * 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)
      * @see UserApi#getUserByName
      */
     default Mono<ResponseEntity<User>> getUserByName(String username,
@@ -95,6 +120,12 @@ public interface UserApiDelegate {
     }
 
     /**
+     * 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)
      * @see UserApi#loginUser
      */
     default Mono<ResponseEntity<String>> loginUser(String username,
@@ -107,6 +138,9 @@ public interface UserApiDelegate {
     }
 
     /**
+     * GET /user/logout : Logs out current logged in user session
+     *
+     * @return successful operation (status code 200)
      * @see UserApi#logoutUser
      */
     default Mono<ResponseEntity<Void>> logoutUser(ServerWebExchange exchange) {
@@ -117,6 +151,13 @@ public interface UserApiDelegate {
     }
 
     /**
+     * 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)
      * @see UserApi#updateUser
      */
     default Mono<ResponseEntity<Void>> updateUser(String username,

samples/server/petstore/springboot-useoptional/src/main/java/org/openapitools/api/AnotherFakeApi.java

@@ -35,6 +35,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/springboot-useoptional/src/main/java/org/openapitools/api/FakeApi.java

@@ -45,6 +45,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") })
@@ -57,6 +64,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) })
@@ -69,6 +83,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) })
@@ -90,6 +111,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) })
@@ -102,6 +130,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) })
@@ -114,6 +149,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") })
@@ -126,6 +168,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") })
@@ -138,6 +187,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) })
@@ -160,6 +216,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", })
@@ -175,6 +252,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"),
@@ -188,6 +280,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") })
@@ -199,6 +303,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") })
@@ -211,6 +321,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") })
@@ -223,6 +340,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") })
@@ -234,6 +362,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/springboot-useoptional/src/main/java/org/openapitools/api/FakeClassnameTestApi.java

@@ -35,6 +35,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/springboot-useoptional/src/main/java/org/openapitools/api/PetApi.java

@@ -37,6 +37,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"),
@@ -55,6 +62,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"),
@@ -72,6 +87,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"),
@@ -104,6 +127,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"),
@@ -136,6 +168,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", })
@@ -166,6 +207,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"),
@@ -186,6 +236,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"),
@@ -203,6 +261,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"),