r better doc (#13447)

OpenAPITools · Sep 17, 2022 · 863dbc7 · 863dbc7
1 parent 7e87b5d
commit 863dbc7
Show file tree

Hide file tree

Showing 38 changed files with 259 additions and 111 deletions.
diff --git a/modules/openapi-generator/src/main/resources/r/api_doc.mustache b/modules/openapi-generator/src/main/resources/r/api_doc.mustache
@@ -21,13 +21,17 @@ Method | HTTP request | Description
 ```R
 library({{{packageName}}})
 
+{{#summary}}
+# {{{.}}}
+#
+{{/summary}}
 {{#allParams}}
+{{#-first}}
+# prepare function argument(s)
+{{/-first}}
 var_{{{paramName}}} <- {{{vendorExtensions.x-r-example}}} # {{{dataType}}} | {{{description}}}{{^required}} (Optional){{/required}}
 {{/allParams}}
 
-{{#summary}}
-# {{{.}}}
-{{/summary}}
 {{#generateWrapper}}
 api_instance <- {{#lambda.lowercase}}{{{packageName}}}{{/lambda.lowercase}}_api$new()
 {{/generateWrapper}}
@@ -39,21 +43,21 @@ api_instance <- {{{classname}}}$new()
 {{#isBasic}}
 {{#isBasicBasic}}
 # Configure HTTP basic authorization: {{{name}}}
-api_instance$api_client$username <- Sys.getenv("USERNAME")
-api_instance$api_client$password <- Sys.getenv("PASSWORD")
+{{^-first}}# {{/-first}}api_instance$api_client$username <- Sys.getenv("USERNAME")
+{{^-first}}# {{/-first}}api_instance$api_client$password <- Sys.getenv("PASSWORD")
 {{/isBasicBasic}}
 {{#isBasicBearer}}
 # Configure HTTP bearer authorization: {{{name}}}
-api_instance$api_client$bearer_token <- Sys.getenv("BEARER_TOKEN")
+{{^-first}}# {{/-first}}api_instance$api_client$bearer_token <- Sys.getenv("BEARER_TOKEN")
 {{/isBasicBearer}}
 {{/isBasic}}
 {{#isApiKey}}
 # Configure API key authorization: {{{name}}}
-api_instance$api_client$api_keys["{{{keyParamName}}}"] <- Sys.getenv("API_KEY")
+{{^-first}}# {{/-first}}api_instance$api_client$api_keys["{{{keyParamName}}}"] <- Sys.getenv("API_KEY")
 {{/isApiKey}}
 {{#isOAuth}}
 # Configure OAuth2 access token for authorization: {{{name}}}
-api_instance$api_client$access_token <- Sys.getenv("ACCESS_TOKEN")
+{{^-first}}# {{/-first}}api_instance$api_client$access_token <- Sys.getenv("ACCESS_TOKEN")
 {{/isOAuth}}
 {{/authMethods}}
 {{/hasAuthMethods}}

diff --git a/modules/openapi-generator/src/main/resources/r/model_doc.mustache b/modules/openapi-generator/src/main/resources/r/model_doc.mustache
@@ -6,7 +6,7 @@
 ## Properties
 Name | Type | Description | Notes
 ------------ | ------------- | ------------- | -------------
-{{#vars}}**{{name}}** | {{#isPrimitiveType}}**{{dataType}}**{{/isPrimitiveType}}{{^isPrimitiveType}}[**{{dataType}}**]({{complexType}}.md){{/isPrimitiveType}} | {{description}} | {{^required}}[optional] {{/required}}{{#isReadOnly}}[readonly] {{/isReadOnly}}{{#defaultValue}}[default to {{.}}]{{/defaultValue}}
+{{#vars}}**{{name}}** | {{#isPrimitiveType}}**{{dataType}}**{{/isPrimitiveType}}{{^isPrimitiveType}}[**{{dataType}}**]({{complexType}}.md){{/isPrimitiveType}} | {{description}} | {{^required}}[optional] {{/required}}{{#isReadOnly}}[readonly] {{/isReadOnly}}{{#defaultValue}}[default to {{.}}] {{/defaultValue}}{{#maximum}}[Max: {{{.}}}] {{/maximum}}{{#minimum}}[Min: {{{.}}}] {{/minimum}}{{#isEnum}}[Enum: {{_enum}}] {{/isEnum}}{{#pattern}}[Pattern: {{.}}] {{/pattern}}{{#maxItems}}[Max. items: {{.}}] {{/maxItems}}{{#minItems}}[Min. items: {{.}}] {{/minItems}}{{#maxLength}}[Max. length: {{.}}] {{/maxLength}}{{#minLength}}[Min. length: {{.}}] {{/minLength}}
 {{/vars}}
 
 {{/model}}{{/models}}
diff --git a/samples/client/petstore/R-httr2-wrapper/docs/Animal.md b/samples/client/petstore/R-httr2-wrapper/docs/Animal.md
@@ -5,6 +5,6 @@
 Name | Type | Description | Notes
 ------------ | ------------- | ------------- | -------------
 **className** | **character** |  | 
-**color** | **character** |  | [optional] [default to &quot;red&quot;]
+**color** | **character** |  | [optional] [default to &quot;red&quot;] 
 
 
diff --git a/samples/client/petstore/R-httr2-wrapper/docs/Cat.md b/samples/client/petstore/R-httr2-wrapper/docs/Cat.md
@@ -5,7 +5,7 @@
 Name | Type | Description | Notes
 ------------ | ------------- | ------------- | -------------
 **className** | **character** |  | 
-**color** | **character** |  | [optional] [default to &quot;red&quot;]
+**color** | **character** |  | [optional] [default to &quot;red&quot;] 
 **declawed** | **character** |  | [optional] 
 
 
diff --git a/samples/client/petstore/R-httr2-wrapper/docs/Category.md b/samples/client/petstore/R-httr2-wrapper/docs/Category.md
@@ -6,6 +6,6 @@ A category for a pet
 Name | Type | Description | Notes
 ------------ | ------------- | ------------- | -------------
 **id** | **integer** |  | [optional] 
-**name** | **character** |  | [optional] 
+**name** | **character** |  | [optional] [Pattern: ^[a-zA-Z0-9]+[a-zA-Z0-9\\.\\-_]*[a-zA-Z0-9]+$] 
 
 
diff --git a/samples/client/petstore/R-httr2-wrapper/docs/Dog.md b/samples/client/petstore/R-httr2-wrapper/docs/Dog.md
@@ -5,7 +5,7 @@
 Name | Type | Description | Notes
 ------------ | ------------- | ------------- | -------------
 **className** | **character** |  | 
-**color** | **character** |  | [optional] [default to &quot;red&quot;]
+**color** | **character** |  | [optional] [default to &quot;red&quot;] 
 **breed** | **character** |  | [optional] 
 
 
diff --git a/samples/client/petstore/R-httr2-wrapper/docs/FakeApi.md b/samples/client/petstore/R-httr2-wrapper/docs/FakeApi.md
@@ -20,10 +20,12 @@ test data_file to ensure it's escaped correctly
 ```R
 library(petstore)
 
+# test data_file to ensure it's escaped correctly
+#
+# prepare function argument(s)
 var_dummy <- "dummy_example" # character | dummy required parameter
 var_var_data_file <- "var_data_file_example" # character | header data file (Optional)
 
-# test data_file to ensure it's escaped correctly
 api_instance <- petstore_api$new()
 result <- tryCatch(
              # to save the result into a file, simply add the optional `data_file` parameter, e.g.
@@ -81,9 +83,11 @@ test regular expression to ensure no exception
 ```R
 library(petstore)
 
+# test regular expression to ensure no exception
+#
+# prepare function argument(s)
 var_reg_exp_test <- "reg_exp_test_example" # character | dummy required parameter
 
-# test regular expression to ensure no exception
 api_instance <- petstore_api$new()
 result <- tryCatch(
              api_instance$fake_api$fake_regular_expression(var_reg_exp_test),
@@ -134,10 +138,12 @@ test set query parameter
 ```R
 library(petstore)
 
+# test set query parameter
+#
+# prepare function argument(s)
 var_set_dummy <- list("inner_example") # set[character] | set query
 var_array_dummy <- list("inner_example") # array[character] | array query
 
-# test set query parameter
 api_instance <- petstore_api$new()
 result <- tryCatch(
              api_instance$fake_api$fake_set_query(var_set_dummy, var_array_dummy),

diff --git a/samples/client/petstore/R-httr2-wrapper/docs/Mammal.md b/samples/client/petstore/R-httr2-wrapper/docs/Mammal.md
@@ -7,6 +7,6 @@ Name | Type | Description | Notes
 **hasBaleen** | **character** |  | [optional] 
 **hasTeeth** | **character** |  | [optional] 
 **className** | **character** |  | 
-**type** | **character** |  | [optional] 
+**type** | **character** |  | [optional] [Enum: [plains, mountain, grevys]] 
 
 
diff --git a/samples/client/petstore/R-httr2-wrapper/docs/Order.md b/samples/client/petstore/R-httr2-wrapper/docs/Order.md
@@ -9,7 +9,7 @@ Name | Type | Description | Notes
 **petId** | **integer** |  | [optional] 
 **quantity** | **integer** |  | [optional] 
 **shipDate** | **character** |  | [optional] 
-**status** | **character** | Order Status | [optional] 
-**complete** | **character** |  | [optional] [default to FALSE]
+**status** | **character** | Order Status | [optional] [Enum: [placed, approved, delivered]] 
+**complete** | **character** |  | [optional] [default to FALSE] 
 
 
diff --git a/samples/client/petstore/R-httr2-wrapper/docs/Pet.md b/samples/client/petstore/R-httr2-wrapper/docs/Pet.md
@@ -10,6 +10,6 @@ Name | Type | Description | Notes
 **name** | **character** |  | 
 **photoUrls** | **array[character]** |  | 
 **tags** | [**array[Tag]**](Tag.md) |  | [optional] 
-**status** | **character** | pet status in the store | [optional] 
+**status** | **character** | pet status in the store | [optional] [Enum: [available, pending, sold]] 
 
 
diff --git a/samples/client/petstore/R-httr2-wrapper/docs/PetApi.md b/samples/client/petstore/R-httr2-wrapper/docs/PetApi.md
@@ -27,9 +27,11 @@ Add a new pet to the store
 ```R
 library(petstore)
 
+# Add a new pet to the store
+#
+# prepare function argument(s)
 var_pet <- Pet$new("name_example", list("photoUrls_example"), 123, Category$new(123, "name_example"), list(Tag$new(123, "name_example")), "available") # Pet | Pet object that needs to be added to the store
 
-# Add a new pet to the store
 api_instance <- petstore_api$new()
 # Configure HTTP basic authorization: http_auth
 api_instance$api_client$username <- Sys.getenv("USERNAME")
@@ -90,10 +92,12 @@ Deletes a pet
 ```R
 library(petstore)
 
+# Deletes a pet
+#
+# prepare function argument(s)
 var_pet_id <- 56 # integer | Pet id to delete
 var_api_key <- "api_key_example" # character |  (Optional)
 
-# Deletes a pet
 api_instance <- petstore_api$new()
 # Configure OAuth2 access token for authorization: petstore_auth
 api_instance$api_client$access_token <- Sys.getenv("ACCESS_TOKEN")
@@ -147,9 +151,11 @@ Multiple status values can be provided with comma separated strings
 ```R
 library(petstore)
 
+# Finds Pets by status
+#
+# prepare function argument(s)
 var_status <- list("available") # array[character] | Status values that need to be considered for filter
 
-# Finds Pets by status
 api_instance <- petstore_api$new()
 # Configure OAuth2 access token for authorization: petstore_auth
 api_instance$api_client$access_token <- Sys.getenv("ACCESS_TOKEN")
@@ -209,9 +215,11 @@ Multiple tags can be provided with comma separated strings. Use tag1, tag2, tag3
 ```R
 library(petstore)
 
+# Finds Pets by tags
+#
+# prepare function argument(s)
 var_tags <- list("inner_example") # array[character] | Tags to filter by
 
-# Finds Pets by tags
 api_instance <- petstore_api$new()
 result <- tryCatch(
              # to save the result into a file, simply add the optional `data_file` parameter, e.g.
@@ -269,9 +277,11 @@ Returns a single pet
 ```R
 library(petstore)
 
+# Find pet by ID
+#
+# prepare function argument(s)
 var_pet_id <- 56 # integer | ID of pet to return
 
-# Find pet by ID
 api_instance <- petstore_api$new()
 # Configure HTTP bearer authorization: BearerToken
 api_instance$api_client$bearer_token <- Sys.getenv("BEARER_TOKEN")
@@ -332,9 +342,11 @@ Returns a single pet
 ```R
 library(petstore)
 
+# Find pet by ID (streaming)
+#
+# prepare function argument(s)
 var_pet_id <- 56 # integer | ID of pet to return
 
-# Find pet by ID (streaming)
 api_instance <- petstore_api$new()
 # Configure API key authorization: api_key
 api_instance$api_client$api_keys["api_key"] <- Sys.getenv("API_KEY")
@@ -397,9 +409,11 @@ Header test
 ```R
 library(petstore)
 
+# Header test
+#
+# prepare function argument(s)
 var_header_test_int <- 56 # integer | header test int
 
-# Header test
 api_instance <- petstore_api$new()
 # Configure API key authorization: api_key
 api_instance$api_client$api_keys["api_key"] <- Sys.getenv("API_KEY")
@@ -462,9 +476,11 @@ Update an existing pet
 ```R
 library(petstore)
 
+# Update an existing pet
+#
+# prepare function argument(s)
 var_pet <- Pet$new("name_example", list("photoUrls_example"), 123, Category$new(123, "name_example"), list(Tag$new(123, "name_example")), "available") # Pet | Pet object that needs to be added to the store
 
-# Update an existing pet
 api_instance <- petstore_api$new()
 # Configure OAuth2 access token for authorization: petstore_auth
 api_instance$api_client$access_token <- Sys.getenv("ACCESS_TOKEN")
@@ -526,11 +542,13 @@ Updates a pet in the store with form data
 ```R
 library(petstore)
 
+# Updates a pet in the store with form data
+#
+# prepare function argument(s)
 var_pet_id <- 56 # integer | ID of pet that needs to be updated
 var_name <- "name_example" # character | Updated name of the pet (Optional)
 var_status <- "status_example" # character | Updated status of the pet (Optional)
 
-# Updates a pet in the store with form data
 api_instance <- petstore_api$new()
 result <- tryCatch(
              api_instance$pet_api$update_pet_with_form(var_pet_id, name = var_name, status = var_status),
@@ -583,11 +601,13 @@ uploads an image
 ```R
 library(petstore)
 
+# uploads an image
+#
+# prepare function argument(s)
 var_pet_id <- 56 # integer | ID of pet to update
 var_additional_metadata <- "additional_metadata_example" # character | Additional data to pass to server (Optional)
 var_file <- File.new('/path/to/file') # data.frame | file to upload (Optional)
 
-# uploads an image
 api_instance <- petstore_api$new()
 # Configure OAuth2 access token for authorization: petstore_auth
 api_instance$api_client$access_token <- Sys.getenv("ACCESS_TOKEN")

diff --git a/samples/client/petstore/R-httr2-wrapper/docs/StoreApi.md b/samples/client/petstore/R-httr2-wrapper/docs/StoreApi.md
@@ -21,9 +21,11 @@ For valid response try integer IDs with value < 1000. Anything above 1000 or non
 ```R
 library(petstore)
 
+# Delete purchase order by ID
+#
+# prepare function argument(s)
 var_order_id <- "order_id_example" # character | ID of the order that needs to be deleted
 
-# Delete purchase order by ID
 api_instance <- petstore_api$new()
 result <- tryCatch(
              api_instance$store_api$delete_order(var_order_id),
@@ -75,8 +77,9 @@ Returns a map of status codes to quantities
 ```R
 library(petstore)
 
-
 # Returns pet inventories by status
+#
+
 api_instance <- petstore_api$new()
 # Configure API key authorization: api_key
 api_instance$api_client$api_keys["api_key"] <- Sys.getenv("API_KEY")
@@ -132,9 +135,11 @@ For valid response try integer IDs with value <= 5 or > 10. Other values will ge
 ```R
 library(petstore)
 
+# Find purchase order by ID
+#
+# prepare function argument(s)
 var_order_id <- 56 # integer | ID of pet that needs to be fetched
 
-# Find purchase order by ID
 api_instance <- petstore_api$new()
 result <- tryCatch(
              # to save the result into a file, simply add the optional `data_file` parameter, e.g.
@@ -193,9 +198,11 @@ Place an order for a pet
 ```R
 library(petstore)
 
+# Place an order for a pet
+#
+# prepare function argument(s)
 var_order <- Order$new(123, 123, 123, "shipDate_example", "placed", "complete_example") # Order | order placed for purchasing the pet
 
-# Place an order for a pet
 api_instance <- petstore_api$new()
 result <- tryCatch(
              # to save the result into a file, simply add the optional `data_file` parameter, e.g.