From fbc350b364a9e57c964390e7678af4a8976b15a3 Mon Sep 17 00:00:00 2001
From: William Cheng <wing328hk@gmail.com>
Date: Sun, 26 Jun 2022 11:25:09 +0800
Subject: [PATCH] improve r documentation, readme, code sample

---
 .../src/main/resources/r/README.mustache      |  5 +++
 .../src/main/resources/r/api_doc.mustache     | 12 ++++--
 samples/client/petstore/R/README.md           |  5 +++
 samples/client/petstore/R/docs/FakeApi.md     |  8 ++--
 samples/client/petstore/R/docs/PetApi.md      | 40 ++++++++++++-------
 samples/client/petstore/R/docs/StoreApi.md    | 14 +++++--
 samples/client/petstore/R/docs/UserApi.md     | 20 ++++++----
 7 files changed, 71 insertions(+), 33 deletions(-)

diff --git a/modules/openapi-generator/src/main/resources/r/README.mustache b/modules/openapi-generator/src/main/resources/r/README.mustache
index 6f47360315d..1da3dffd0cd 100644
--- a/modules/openapi-generator/src/main/resources/r/README.mustache
+++ b/modules/openapi-generator/src/main/resources/r/README.mustache
@@ -52,6 +52,11 @@ library(devtools)
 install_github("{{{gitUserId}}}/{{{gitRepoId}}}")
 ```
 
+To install the package from a local file:
+```R
+install.packages("{{{packageName}}}_{{{packageVersion}}}.tar.gz", repos = NULL, type = "source")
+```
+
 ### Usage
 
 ```R
diff --git a/modules/openapi-generator/src/main/resources/r/api_doc.mustache b/modules/openapi-generator/src/main/resources/r/api_doc.mustache
index 40b00753348..f5fe834c30d 100644
--- a/modules/openapi-generator/src/main/resources/r/api_doc.mustache
+++ b/modules/openapi-generator/src/main/resources/r/api_doc.mustache
@@ -11,7 +11,7 @@ Method | HTTP request | Description
 {{#operations}}
 {{#operation}}
 # **{{operationId}}**
-> {{#returnType}}{{.}} {{/returnType}}{{operationId}}({{#requiredParams}}{{{paramName}}}{{^-last}}, {{/-last}}{{/requiredParams}}{{#optionalParams}}{{#-first}}{{#requiredParams.0}}, {{/requiredParams.0}}{{/-first}}{{{paramName}}}{{#defaultValue}}={{{.}}}{{/defaultValue}}{{^defaultValue}}=var.{{{paramName}}}{{/defaultValue}}{{^-last}}, {{/-last}}{{/optionalParams}})
+> {{#returnType}}{{.}} {{/returnType}}{{operationId}}({{#requiredParams}}{{{paramName}}}{{^-last}}, {{/-last}}{{/requiredParams}}{{#optionalParams}}{{#-first}}{{#requiredParams.0}}, {{/requiredParams.0}}{{/-first}}{{{paramName}}}{{#defaultValue}} = {{{.}}}{{/defaultValue}}{{^defaultValue}} = var.{{{paramName}}}{{/defaultValue}}{{^-last}}, {{/-last}}{{/optionalParams}})
 
 {{{summary}}}{{#notes}}
 
@@ -49,11 +49,15 @@ api_instance$api_client$access_token <- 'TODO_YOUR_ACCESS_TOKEN';
 {{#returnExceptionOnFailure}}
 {{#useRlangExceptionHandling}}
 result <- tryCatch(
-             api_instance${{{operationId}}}({{#requiredParams}}var_{{{paramName}}}{{^-last}}, {{/-last}}{{/requiredParams}}{{#optionalParams}}{{#-first}}{{#requiredParams.0}}, {{/requiredParams.0}}{{/-first}}{{{paramName}}}=var_{{{paramName}}}{{^-last}}, {{/-last}}{{/optionalParams}}),
+             {{#returnType}}
+             # to save the result into a file, simply add the optional `data_file` parameter, e.g.
+             # api_instance${{{operationId}}}({{#requiredParams}}var_{{{paramName}}}{{^-last}}, {{/-last}}{{/requiredParams}}{{#optionalParams}}{{#-first}}{{#requiredParams.0}}, {{/requiredParams.0}}{{/-first}}{{{paramName}}} = var_{{{paramName}}}{{^-last}}, {{/-last}}{{/optionalParams}}{{#allParams}}{{#-first}}, {{/-first}}{{/allParams}}data_file = "result.txt"),
+             {{/returnType}}
+             api_instance${{{operationId}}}({{#requiredParams}}var_{{{paramName}}}{{^-last}}, {{/-last}}{{/requiredParams}}{{#optionalParams}}{{#-first}}{{#requiredParams.0}}, {{/requiredParams.0}}{{/-first}}{{{paramName}}} = var_{{{paramName}}}{{^-last}}, {{/-last}}{{/optionalParams}}),
              ApiException = function(ex) ex
           )
 # In case of error, print the error object
-if(!is.null(result$ApiException)) {
+if (!is.null(result$ApiException)) {
   cat(result$ApiException$toString())
 } else {
   {{#returnType}}
@@ -68,7 +72,7 @@ if(!is.null(result$ApiException)) {
 {{/useRlangExceptionHandling}}
 {{/returnExceptionOnFailure}}
 {{^useRlangExceptionHandling}}
-{{#returnType}}result <- {{/returnType}}api_instance${{{operationId}}}({{#requiredParams}}var_{{{paramName}}}{{^-last}}, {{/-last}}{{/requiredParams}}{{#optionalParams}}{{#-first}}{{#requiredParams.0}}, {{/requiredParams.0}}{{/-first}}{{{paramName}}}=var_{{{paramName}}}{{^-last}}, {{/-last}}{{/optionalParams}})
+{{#returnType}}result <- {{/returnType}}api_instance${{{operationId}}}({{#requiredParams}}var_{{{paramName}}}{{^-last}}, {{/-last}}{{/requiredParams}}{{#optionalParams}}{{#-first}}{{#requiredParams.0}}, {{/requiredParams.0}}{{/-first}}{{{paramName}}} = var_{{{paramName}}}{{^-last}}, {{/-last}}{{/optionalParams}})
 {{#returnType}}
 dput(result)
 {{/returnType}}
diff --git a/samples/client/petstore/R/README.md b/samples/client/petstore/R/README.md
index c853c8087eb..eb829f1e420 100644
--- a/samples/client/petstore/R/README.md
+++ b/samples/client/petstore/R/README.md
@@ -44,6 +44,11 @@ library(devtools)
 install_github("GIT_USER_ID/GIT_REPO_ID")
 ```
 
+To install the package from a local file:
+```R
+install.packages("petstore_1.0.0.tar.gz", repos = NULL, type = "source")
+```
+
 ### Usage
 
 ```R
diff --git a/samples/client/petstore/R/docs/FakeApi.md b/samples/client/petstore/R/docs/FakeApi.md
index 8de1fc175c5..55132bdfcf7 100644
--- a/samples/client/petstore/R/docs/FakeApi.md
+++ b/samples/client/petstore/R/docs/FakeApi.md
@@ -8,7 +8,7 @@ Method | HTTP request | Description
 
 
 # **FakeDataFile**
-> User FakeDataFile(dummy, var_data_file=var.var_data_file)
+> User FakeDataFile(dummy, var_data_file = var.var_data_file)
 
 test data_file to ensure it's escaped correctly
 
@@ -24,11 +24,13 @@ var_var_data_file <- 'var_data_file_example' # character | header data file
 #test data_file to ensure it's escaped correctly
 api_instance <- FakeApi$new()
 result <- tryCatch(
-             api_instance$FakeDataFile(var_dummy, var_data_file=var_var_data_file),
+             # to save the result into a file, simply add the optional `data_file` parameter, e.g.
+             # api_instance$FakeDataFile(var_dummy, var_data_file = var_var_data_file, data_file = "result.txt"),
+             api_instance$FakeDataFile(var_dummy, var_data_file = var_var_data_file),
              ApiException = function(ex) ex
           )
 # In case of error, print the error object
-if(!is.null(result$ApiException)) {
+if (!is.null(result$ApiException)) {
   cat(result$ApiException$toString())
 } else {
   # deserialized response object
diff --git a/samples/client/petstore/R/docs/PetApi.md b/samples/client/petstore/R/docs/PetApi.md
index 88dd0b503d7..d302a3bf707 100644
--- a/samples/client/petstore/R/docs/PetApi.md
+++ b/samples/client/petstore/R/docs/PetApi.md
@@ -32,11 +32,13 @@ api_instance <- PetApi$new()
 # Configure OAuth2 access token for authorization: petstore_auth
 api_instance$api_client$access_token <- 'TODO_YOUR_ACCESS_TOKEN';
 result <- tryCatch(
+             # to save the result into a file, simply add the optional `data_file` parameter, e.g.
+             # api_instance$AddPet(var_pet, data_file = "result.txt"),
              api_instance$AddPet(var_pet),
              ApiException = function(ex) ex
           )
 # In case of error, print the error object
-if(!is.null(result$ApiException)) {
+if (!is.null(result$ApiException)) {
   cat(result$ApiException$toString())
 } else {
   # deserialized response object
@@ -74,7 +76,7 @@ Name | Type | Description  | Notes
 | **405** | Invalid input |  -  |
 
 # **DeletePet**
-> DeletePet(pet_id, api_key=var.api_key)
+> DeletePet(pet_id, api_key = var.api_key)
 
 Deletes a pet
 
@@ -92,11 +94,11 @@ api_instance <- PetApi$new()
 # Configure OAuth2 access token for authorization: petstore_auth
 api_instance$api_client$access_token <- 'TODO_YOUR_ACCESS_TOKEN';
 result <- tryCatch(
-             api_instance$DeletePet(var_pet_id, api_key=var_api_key),
+             api_instance$DeletePet(var_pet_id, api_key = var_api_key),
              ApiException = function(ex) ex
           )
 # In case of error, print the error object
-if(!is.null(result$ApiException)) {
+if (!is.null(result$ApiException)) {
   cat(result$ApiException$toString())
 } else {
   # response headers
@@ -149,11 +151,13 @@ api_instance <- PetApi$new()
 # Configure OAuth2 access token for authorization: petstore_auth
 api_instance$api_client$access_token <- 'TODO_YOUR_ACCESS_TOKEN';
 result <- tryCatch(
+             # to save the result into a file, simply add the optional `data_file` parameter, e.g.
+             # api_instance$FindPetsByStatus(var_status, data_file = "result.txt"),
              api_instance$FindPetsByStatus(var_status),
              ApiException = function(ex) ex
           )
 # In case of error, print the error object
-if(!is.null(result$ApiException)) {
+if (!is.null(result$ApiException)) {
   cat(result$ApiException$toString())
 } else {
   # deserialized response object
@@ -208,11 +212,13 @@ api_instance <- PetApi$new()
 # Configure OAuth2 access token for authorization: petstore_auth
 api_instance$api_client$access_token <- 'TODO_YOUR_ACCESS_TOKEN';
 result <- tryCatch(
+             # to save the result into a file, simply add the optional `data_file` parameter, e.g.
+             # api_instance$FindPetsByTags(var_tags, data_file = "result.txt"),
              api_instance$FindPetsByTags(var_tags),
              ApiException = function(ex) ex
           )
 # In case of error, print the error object
-if(!is.null(result$ApiException)) {
+if (!is.null(result$ApiException)) {
   cat(result$ApiException$toString())
 } else {
   # deserialized response object
@@ -267,11 +273,13 @@ api_instance <- PetApi$new()
 # Configure API key authorization: api_key
 api_instance$api_client$api_keys['api_key'] <- 'TODO_YOUR_API_KEY';
 result <- tryCatch(
+             # to save the result into a file, simply add the optional `data_file` parameter, e.g.
+             # api_instance$GetPetById(var_pet_id, data_file = "result.txt"),
              api_instance$GetPetById(var_pet_id),
              ApiException = function(ex) ex
           )
 # In case of error, print the error object
-if(!is.null(result$ApiException)) {
+if (!is.null(result$ApiException)) {
   cat(result$ApiException$toString())
 } else {
   # deserialized response object
@@ -327,11 +335,13 @@ api_instance <- PetApi$new()
 # Configure OAuth2 access token for authorization: petstore_auth
 api_instance$api_client$access_token <- 'TODO_YOUR_ACCESS_TOKEN';
 result <- tryCatch(
+             # to save the result into a file, simply add the optional `data_file` parameter, e.g.
+             # api_instance$UpdatePet(var_pet, data_file = "result.txt"),
              api_instance$UpdatePet(var_pet),
              ApiException = function(ex) ex
           )
 # In case of error, print the error object
-if(!is.null(result$ApiException)) {
+if (!is.null(result$ApiException)) {
   cat(result$ApiException$toString())
 } else {
   # deserialized response object
@@ -371,7 +381,7 @@ Name | Type | Description  | Notes
 | **405** | Validation exception |  -  |
 
 # **UpdatePetWithForm**
-> UpdatePetWithForm(pet_id, name=var.name, status=var.status)
+> UpdatePetWithForm(pet_id, name = var.name, status = var.status)
 
 Updates a pet in the store with form data
 
@@ -390,11 +400,11 @@ api_instance <- PetApi$new()
 # Configure OAuth2 access token for authorization: petstore_auth
 api_instance$api_client$access_token <- 'TODO_YOUR_ACCESS_TOKEN';
 result <- tryCatch(
-             api_instance$UpdatePetWithForm(var_pet_id, name=var_name, status=var_status),
+             api_instance$UpdatePetWithForm(var_pet_id, name = var_name, status = var_status),
              ApiException = function(ex) ex
           )
 # In case of error, print the error object
-if(!is.null(result$ApiException)) {
+if (!is.null(result$ApiException)) {
   cat(result$ApiException$toString())
 } else {
   # response headers
@@ -431,7 +441,7 @@ void (empty response body)
 | **405** | Invalid input |  -  |
 
 # **UploadFile**
-> ModelApiResponse UploadFile(pet_id, additional_metadata=var.additional_metadata, file=var.file)
+> ModelApiResponse UploadFile(pet_id, additional_metadata = var.additional_metadata, file = var.file)
 
 uploads an image
 
@@ -450,11 +460,13 @@ api_instance <- PetApi$new()
 # Configure OAuth2 access token for authorization: petstore_auth
 api_instance$api_client$access_token <- 'TODO_YOUR_ACCESS_TOKEN';
 result <- tryCatch(
-             api_instance$UploadFile(var_pet_id, additional_metadata=var_additional_metadata, file=var_file),
+             # to save the result into a file, simply add the optional `data_file` parameter, e.g.
+             # api_instance$UploadFile(var_pet_id, additional_metadata = var_additional_metadata, file = var_file, data_file = "result.txt"),
+             api_instance$UploadFile(var_pet_id, additional_metadata = var_additional_metadata, file = var_file),
              ApiException = function(ex) ex
           )
 # In case of error, print the error object
-if(!is.null(result$ApiException)) {
+if (!is.null(result$ApiException)) {
   cat(result$ApiException$toString())
 } else {
   # deserialized response object
diff --git a/samples/client/petstore/R/docs/StoreApi.md b/samples/client/petstore/R/docs/StoreApi.md
index f62dcf6e76b..2caef65f3d2 100644
--- a/samples/client/petstore/R/docs/StoreApi.md
+++ b/samples/client/petstore/R/docs/StoreApi.md
@@ -30,7 +30,7 @@ result <- tryCatch(
              ApiException = function(ex) ex
           )
 # In case of error, print the error object
-if(!is.null(result$ApiException)) {
+if (!is.null(result$ApiException)) {
   cat(result$ApiException$toString())
 } else {
   # response headers
@@ -82,11 +82,13 @@ api_instance <- StoreApi$new()
 # Configure API key authorization: api_key
 api_instance$api_client$api_keys['api_key'] <- 'TODO_YOUR_API_KEY';
 result <- tryCatch(
+             # to save the result into a file, simply add the optional `data_file` parameter, e.g.
+             # api_instance$GetInventory(data_file = "result.txt"),
              api_instance$GetInventory(),
              ApiException = function(ex) ex
           )
 # In case of error, print the error object
-if(!is.null(result$ApiException)) {
+if (!is.null(result$ApiException)) {
   cat(result$ApiException$toString())
 } else {
   # deserialized response object
@@ -135,11 +137,13 @@ var_order_id <- 56 # integer | ID of pet that needs to be fetched
 #Find purchase order by ID
 api_instance <- StoreApi$new()
 result <- tryCatch(
+             # to save the result into a file, simply add the optional `data_file` parameter, e.g.
+             # api_instance$GetOrderById(var_order_id, data_file = "result.txt"),
              api_instance$GetOrderById(var_order_id),
              ApiException = function(ex) ex
           )
 # In case of error, print the error object
-if(!is.null(result$ApiException)) {
+if (!is.null(result$ApiException)) {
   cat(result$ApiException$toString())
 } else {
   # deserialized response object
@@ -193,11 +197,13 @@ var_order <- Order$new(123, 123, 123, "shipDate_example", "placed", "complete_ex
 #Place an order for a pet
 api_instance <- StoreApi$new()
 result <- tryCatch(
+             # to save the result into a file, simply add the optional `data_file` parameter, e.g.
+             # api_instance$PlaceOrder(var_order, data_file = "result.txt"),
              api_instance$PlaceOrder(var_order),
              ApiException = function(ex) ex
           )
 # In case of error, print the error object
-if(!is.null(result$ApiException)) {
+if (!is.null(result$ApiException)) {
   cat(result$ApiException$toString())
 } else {
   # deserialized response object
diff --git a/samples/client/petstore/R/docs/UserApi.md b/samples/client/petstore/R/docs/UserApi.md
index 62fbbe4970a..d292094b7e8 100644
--- a/samples/client/petstore/R/docs/UserApi.md
+++ b/samples/client/petstore/R/docs/UserApi.md
@@ -36,7 +36,7 @@ result <- tryCatch(
              ApiException = function(ex) ex
           )
 # In case of error, print the error object
-if(!is.null(result$ApiException)) {
+if (!is.null(result$ApiException)) {
   cat(result$ApiException$toString())
 } else {
   # response headers
@@ -92,7 +92,7 @@ result <- tryCatch(
              ApiException = function(ex) ex
           )
 # In case of error, print the error object
-if(!is.null(result$ApiException)) {
+if (!is.null(result$ApiException)) {
   cat(result$ApiException$toString())
 } else {
   # response headers
@@ -148,7 +148,7 @@ result <- tryCatch(
              ApiException = function(ex) ex
           )
 # In case of error, print the error object
-if(!is.null(result$ApiException)) {
+if (!is.null(result$ApiException)) {
   cat(result$ApiException$toString())
 } else {
   # response headers
@@ -204,7 +204,7 @@ result <- tryCatch(
              ApiException = function(ex) ex
           )
 # In case of error, print the error object
-if(!is.null(result$ApiException)) {
+if (!is.null(result$ApiException)) {
   cat(result$ApiException$toString())
 } else {
   # response headers
@@ -255,11 +255,13 @@ var_username <- 'username_example' # character | The name that needs to be fetch
 #Get user by user name
 api_instance <- UserApi$new()
 result <- tryCatch(
+             # to save the result into a file, simply add the optional `data_file` parameter, e.g.
+             # api_instance$GetUserByName(var_username, data_file = "result.txt"),
              api_instance$GetUserByName(var_username),
              ApiException = function(ex) ex
           )
 # In case of error, print the error object
-if(!is.null(result$ApiException)) {
+if (!is.null(result$ApiException)) {
   cat(result$ApiException$toString())
 } else {
   # deserialized response object
@@ -314,11 +316,13 @@ var_password <- 'password_example' # character | The password for login in clear
 #Logs user into the system
 api_instance <- UserApi$new()
 result <- tryCatch(
+             # to save the result into a file, simply add the optional `data_file` parameter, e.g.
+             # api_instance$LoginUser(var_username, var_password, data_file = "result.txt"),
              api_instance$LoginUser(var_username, var_password),
              ApiException = function(ex) ex
           )
 # In case of error, print the error object
-if(!is.null(result$ApiException)) {
+if (!is.null(result$ApiException)) {
   cat(result$ApiException$toString())
 } else {
   # deserialized response object
@@ -377,7 +381,7 @@ result <- tryCatch(
              ApiException = function(ex) ex
           )
 # In case of error, print the error object
-if(!is.null(result$ApiException)) {
+if (!is.null(result$ApiException)) {
   cat(result$ApiException$toString())
 } else {
   # response headers
@@ -431,7 +435,7 @@ result <- tryCatch(
              ApiException = function(ex) ex
           )
 # In case of error, print the error object
-if(!is.null(result$ApiException)) {
+if (!is.null(result$ApiException)) {
   cat(result$ApiException$toString())
 } else {
   # response headers
-- 
GitLab