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