Skip to content

feat: Added doc comments to Rust reqwest-trait template #20591

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
wing328 merged 1 commit into from
Feb 5, 2025
Merged

feat: Added doc comments to Rust reqwest-trait template #20591

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions modules/openapi-generator/src/main/resources/rust/reqwest-trait/api.mustache
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,12 @@ use super::{Error, configuration};
pub trait {{{classname}}}: Send + Sync {
{{#operations}}
{{#operation}}

Copy link
Contributor Author

@ranger-ross ranger-ross Feb 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

note: this newline is intentional to give a bit more space between functions to make them easier to read.

/// {{{httpMethod}}} {{{path}}}
{{^notes.empty}}
///
/// {{{notes}}}
{{/notes.empty}}
{{#vendorExtensions.x-group-parameters}}
async fn {{{operationId}}}(&self, {{#allParams}}{{#-first}} params: {{{operationIdCamelCase}}}Params {{/-first}}{{/allParams}}) -> Result<{{#supportMultipleResponses}}ResponseContent<{{{operationIdCamelCase}}}Success>{{/supportMultipleResponses}}{{^supportMultipleResponses}}{{^returnType}}(){{/returnType}}{{{returnType}}}{{/supportMultipleResponses}}, Error<{{{operationIdCamelCase}}}Error>>;
{{/vendorExtensions.x-group-parameters}}
Expand Down
6 changes: 4 additions & 2 deletions modules/openapi-generator/src/test/resources/3_0/rust/petstore.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ paths:
tags:
- pet
summary: Add a new pet to the store
description: ''
description: This is the description for the addPet operation
operationId: addPet
responses:
'200':
Expand Down Expand Up @@ -76,7 +76,9 @@ paths:
tags:
- pet
summary: Finds Pets by status
description: Multiple status values can be provided with comma separated strings
description: |
Multiple status values can be provided with comma separated strings.
This is also a multi-line description to test rust doc comments
operationId: findPetsByStatus
parameters:
- name: status
Expand Down
4 changes: 2 additions & 2 deletions samples/client/petstore/rust/hyper/petstore/docs/PetApi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Method | HTTP request | Description
> models::Pet add_pet(pet)
Add a new pet to the store


This is the description for the addPet operation

### Parameters

Expand Down Expand Up @@ -81,7 +81,7 @@ Name | Type | Description | Required | Notes
> Vec<models::Pet> find_pets_by_status(status, r#type)
Finds Pets by status

Multiple status values can be provided with comma separated strings
Multiple status values can be provided with comma separated strings. This is also a multi-line description to test rust doc comments

### Parameters

Expand Down
4 changes: 2 additions & 2 deletions samples/client/petstore/rust/hyper0x/petstore/docs/PetApi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Method | HTTP request | Description
> models::Pet add_pet(pet)
Add a new pet to the store


This is the description for the addPet operation

### Parameters

Expand Down Expand Up @@ -81,7 +81,7 @@ Name | Type | Description | Required | Notes
> Vec<models::Pet> find_pets_by_status(status, r#type)
Finds Pets by status

Multiple status values can be provided with comma separated strings
Multiple status values can be provided with comma separated strings. This is also a multi-line description to test rust doc comments

### Parameters

Expand Down
4 changes: 2 additions & 2 deletions samples/client/petstore/rust/reqwest-trait/petstore/docs/PetApi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Method | HTTP request | Description
> models::Pet add_pet(pet)
Add a new pet to the store


This is the description for the addPet operation

### Parameters

Expand Down Expand Up @@ -81,7 +81,7 @@ Name | Type | Description | Required | Notes
> Vec<models::Pet> find_pets_by_status(status, r#type)
Finds Pets by status

Multiple status values can be provided with comma separated strings
Multiple status values can be provided with comma separated strings. This is also a multi-line description to test rust doc comments

### Parameters

Expand Down
2 changes: 2 additions & 0 deletions samples/client/petstore/rust/reqwest-trait/petstore/src/apis/fake_api.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,8 @@ use super::{Error, configuration};
#[cfg_attr(feature = "mockall", automock)]
#[async_trait]
pub trait FakeApi: Send + Sync {

/// GET /fake/user/{user_name}
async fn test_nullable_required_param<'user_name, 'dummy_required_nullable_param, 'uppercase, 'content>(&self, user_name: &'user_name str, dummy_required_nullable_param: Option<&'dummy_required_nullable_param str>, uppercase: Option<&'uppercase str>, content: Option<&'content str>) -> Result<(), Error<TestNullableRequiredParamError>>;
}

Expand Down
28 changes: 26 additions & 2 deletions samples/client/petstore/rust/reqwest-trait/petstore/src/apis/pet_api.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,13 +21,37 @@ use super::{Error, configuration};
#[cfg_attr(feature = "mockall", automock)]
#[async_trait]
pub trait PetApi: Send + Sync {

/// POST /pet
///
/// This is the description for the addPet operation
async fn add_pet<'pet>(&self, pet: models::Pet) -> Result<models::Pet, Error<AddPetError>>;

/// DELETE /pet/{petId}
async fn delete_pet<'pet_id, 'api_key>(&self, pet_id: i64, api_key: Option<&'api_key str>) -> Result<(), Error<DeletePetError>>;

/// GET /pet/findByStatus
///
/// Multiple status values can be provided with comma separated strings. This is also a multi-line description to test rust doc comments
async fn find_pets_by_status<'status, 'r_type>(&self, status: Vec<String>, r#type: Option<Vec<String>>) -> Result<Vec<models::Pet>, Error<FindPetsByStatusError>>;

/// GET /pet/findByTags
///
/// Multiple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing.
async fn find_pets_by_tags<'tags>(&self, tags: Vec<String>) -> Result<Vec<models::Pet>, Error<FindPetsByTagsError>>;

/// GET /pet/{petId}
///
/// Returns a single pet
async fn get_pet_by_id<'pet_id>(&self, pet_id: i64) -> Result<models::Pet, Error<GetPetByIdError>>;

/// PUT /pet
async fn update_pet<'pet>(&self, pet: models::Pet) -> Result<models::Pet, Error<UpdatePetError>>;

/// POST /pet/{petId}
async fn update_pet_with_form<'pet_id, 'name, 'status>(&self, pet_id: i64, name: Option<&'name str>, status: Option<&'status str>) -> Result<(), Error<UpdatePetWithFormError>>;

/// POST /pet/{petId}/uploadImage
async fn upload_file<'pet_id, 'additional_metadata, 'file>(&self, pet_id: i64, additional_metadata: Option<&'additional_metadata str>, file: Option<std::path::PathBuf>) -> Result<models::ApiResponse, Error<UploadFileError>>;
}

Expand All @@ -45,7 +69,7 @@ impl PetApiClient {

#[async_trait]
impl PetApi for PetApiClient {
///
/// This is the description for the addPet operation
async fn add_pet<'pet>(&self, pet: models::Pet) -> Result<models::Pet, Error<AddPetError>> {
let local_var_configuration = &self.configuration;

Expand Down Expand Up @@ -111,7 +135,7 @@ impl PetApi for PetApiClient {
}
}

/// Multiple status values can be provided with comma separated strings
/// Multiple status values can be provided with comma separated strings. This is also a multi-line description to test rust doc comments
async fn find_pets_by_status<'status, 'r_type>(&self, status: Vec<String>, r#type: Option<Vec<String>>) -> Result<Vec<models::Pet>, Error<FindPetsByStatusError>> {
let local_var_configuration = &self.configuration;

Expand Down
14 changes: 14 additions & 0 deletions samples/client/petstore/rust/reqwest-trait/petstore/src/apis/store_api.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,9 +21,23 @@ use super::{Error, configuration};
#[cfg_attr(feature = "mockall", automock)]
#[async_trait]
pub trait StoreApi: Send + Sync {

/// DELETE /store/order/{orderId}
///
/// For valid response try integer IDs with value < 1000. Anything above 1000 or nonintegers will generate API errors
async fn delete_order<'order_id>(&self, order_id: &'order_id str) -> Result<(), Error<DeleteOrderError>>;

/// GET /store/inventory
///
/// Returns a map of status codes to quantities
async fn get_inventory<>(&self, ) -> Result<std::collections::HashMap<String, i32>, Error<GetInventoryError>>;

/// GET /store/order/{orderId}
///
/// For valid response try integer IDs with value <= 5 or > 10. Other values will generate exceptions
async fn get_order_by_id<'order_id>(&self, order_id: i64) -> Result<models::Order, Error<GetOrderByIdError>>;

/// POST /store/order
async fn place_order<'order>(&self, order: models::Order) -> Result<models::Order, Error<PlaceOrderError>>;
}

Expand Down
8 changes: 8 additions & 0 deletions samples/client/petstore/rust/reqwest-trait/petstore/src/apis/testing_api.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,15 @@ use super::{Error, configuration};
#[cfg_attr(feature = "mockall", automock)]
#[async_trait]
pub trait TestingApi: Send + Sync {

/// GET /tests/fileResponse
///
///
async fn tests_file_response_get<>(&self, ) -> Result<std::path::PathBuf, Error<TestsFileResponseGetError>>;

/// GET /tests/typeTesting
///
///
async fn tests_type_testing_get<>(&self, ) -> Result<models::TypeTesting, Error<TestsTypeTestingGetError>>;
}

Expand Down
22 changes: 22 additions & 0 deletions samples/client/petstore/rust/reqwest-trait/petstore/src/apis/user_api.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,13 +21,35 @@ use super::{Error, configuration};
#[cfg_attr(feature = "mockall", automock)]
#[async_trait]
pub trait UserApi: Send + Sync {

/// POST /user
///
/// This can only be done by the logged in user.
async fn create_user<'user>(&self, user: models::User) -> Result<(), Error<CreateUserError>>;

/// POST /user/createWithArray
async fn create_users_with_array_input<'user>(&self, user: Vec<models::User>) -> Result<(), Error<CreateUsersWithArrayInputError>>;

/// POST /user/createWithList
async fn create_users_with_list_input<'user>(&self, user: Vec<models::User>) -> Result<(), Error<CreateUsersWithListInputError>>;

/// DELETE /user/{username}
///
/// This can only be done by the logged in user.
async fn delete_user<'username>(&self, username: &'username str) -> Result<(), Error<DeleteUserError>>;

/// GET /user/{username}
async fn get_user_by_name<'username>(&self, username: &'username str) -> Result<models::User, Error<GetUserByNameError>>;

/// GET /user/login
async fn login_user<'username, 'password>(&self, username: &'username str, password: &'password str) -> Result<String, Error<LoginUserError>>;

/// GET /user/logout
async fn logout_user<>(&self, ) -> Result<(), Error<LogoutUserError>>;

/// PUT /user/{username}
///
/// This can only be done by the logged in user.
async fn update_user<'username, 'user>(&self, username: &'username str, user: models::User) -> Result<(), Error<UpdateUserError>>;
}

Expand Down
4 changes: 2 additions & 2 deletions samples/client/petstore/rust/reqwest/petstore-async-middleware/docs/PetApi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Method | HTTP request | Description
> models::Pet add_pet(pet)
Add a new pet to the store


This is the description for the addPet operation

### Parameters

Expand Down Expand Up @@ -81,7 +81,7 @@ Name | Type | Description | Required | Notes
> Vec<models::Pet> find_pets_by_status(status, r#type)
Finds Pets by status

Multiple status values can be provided with comma separated strings
Multiple status values can be provided with comma separated strings. This is also a multi-line description to test rust doc comments

### Parameters

Expand Down
4 changes: 2 additions & 2 deletions samples/client/petstore/rust/reqwest/petstore-async-middleware/src/apis/pet_api.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -211,7 +211,7 @@ pub enum UploadFileError {
}


///
/// This is the description for the addPet operation
pub async fn add_pet(configuration: &configuration::Configuration, params: AddPetParams) -> Result<ResponseContent<AddPetSuccess>, Error<AddPetError>> {

let uri_str = format!("{}/pet", configuration.base_path);
Expand Down Expand Up @@ -273,7 +273,7 @@ pub async fn delete_pet(configuration: &configuration::Configuration, params: De
}
}

/// Multiple status values can be provided with comma separated strings
/// Multiple status values can be provided with comma separated strings. This is also a multi-line description to test rust doc comments
pub async fn find_pets_by_status(configuration: &configuration::Configuration, params: FindPetsByStatusParams) -> Result<ResponseContent<FindPetsByStatusSuccess>, Error<FindPetsByStatusError>> {

let uri_str = format!("{}/pet/findByStatus", configuration.base_path);
Expand Down
4 changes: 2 additions & 2 deletions samples/client/petstore/rust/reqwest/petstore-async-tokensource/docs/PetApi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Method | HTTP request | Description
> models::Pet add_pet(pet)
Add a new pet to the store


This is the description for the addPet operation

### Parameters

Expand Down Expand Up @@ -81,7 +81,7 @@ Name | Type | Description | Required | Notes
> Vec<models::Pet> find_pets_by_status(status, r#type)
Finds Pets by status

Multiple status values can be provided with comma separated strings
Multiple status values can be provided with comma separated strings. This is also a multi-line description to test rust doc comments

### Parameters

Expand Down
4 changes: 2 additions & 2 deletions samples/client/petstore/rust/reqwest/petstore-async-tokensource/src/apis/pet_api.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -211,7 +211,7 @@ pub enum UploadFileError {
}


///
/// This is the description for the addPet operation
pub async fn add_pet(configuration: &configuration::Configuration, params: AddPetParams) -> Result<ResponseContent<AddPetSuccess>, Error<AddPetError>> {

let uri_str = format!("{}/pet", configuration.base_path);
Expand Down Expand Up @@ -277,7 +277,7 @@ pub async fn delete_pet(configuration: &configuration::Configuration, params: De
}
}

/// Multiple status values can be provided with comma separated strings
/// Multiple status values can be provided with comma separated strings. This is also a multi-line description to test rust doc comments
pub async fn find_pets_by_status(configuration: &configuration::Configuration, params: FindPetsByStatusParams) -> Result<ResponseContent<FindPetsByStatusSuccess>, Error<FindPetsByStatusError>> {

let uri_str = format!("{}/pet/findByStatus", configuration.base_path);
Expand Down
4 changes: 2 additions & 2 deletions samples/client/petstore/rust/reqwest/petstore-async/docs/PetApi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Method | HTTP request | Description
> models::Pet add_pet(pet)
Add a new pet to the store


This is the description for the addPet operation

### Parameters

Expand Down Expand Up @@ -81,7 +81,7 @@ Name | Type | Description | Required | Notes
> Vec<models::Pet> find_pets_by_status(status, r#type)
Finds Pets by status

Multiple status values can be provided with comma separated strings
Multiple status values can be provided with comma separated strings. This is also a multi-line description to test rust doc comments

### Parameters

Expand Down
4 changes: 2 additions & 2 deletions samples/client/petstore/rust/reqwest/petstore-async/src/apis/pet_api.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -211,7 +211,7 @@ pub enum UploadFileError {
}


///
/// This is the description for the addPet operation
pub async fn add_pet(configuration: &configuration::Configuration, params: AddPetParams) -> Result<ResponseContent<AddPetSuccess>, Error<AddPetError>> {

let uri_str = format!("{}/pet", configuration.base_path);
Expand Down Expand Up @@ -273,7 +273,7 @@ pub async fn delete_pet(configuration: &configuration::Configuration, params: De
}
}

/// Multiple status values can be provided with comma separated strings
/// Multiple status values can be provided with comma separated strings. This is also a multi-line description to test rust doc comments
pub async fn find_pets_by_status(configuration: &configuration::Configuration, params: FindPetsByStatusParams) -> Result<ResponseContent<FindPetsByStatusSuccess>, Error<FindPetsByStatusError>> {

let uri_str = format!("{}/pet/findByStatus", configuration.base_path);
Expand Down
4 changes: 2 additions & 2 deletions samples/client/petstore/rust/reqwest/petstore-avoid-box/docs/PetApi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Method | HTTP request | Description
> models::Pet add_pet(pet)
Add a new pet to the store


This is the description for the addPet operation

### Parameters

Expand Down Expand Up @@ -81,7 +81,7 @@ Name | Type | Description | Required | Notes
> Vec<models::Pet> find_pets_by_status(status, r#type)
Finds Pets by status

Multiple status values can be provided with comma separated strings
Multiple status values can be provided with comma separated strings. This is also a multi-line description to test rust doc comments

### Parameters

Expand Down
4 changes: 2 additions & 2 deletions samples/client/petstore/rust/reqwest/petstore-avoid-box/src/apis/pet_api.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -211,7 +211,7 @@ pub enum UploadFileError {
}


///
/// This is the description for the addPet operation
pub async fn add_pet(configuration: &configuration::Configuration, params: AddPetParams) -> Result<ResponseContent<AddPetSuccess>, Error<AddPetError>> {

let uri_str = format!("{}/pet", configuration.base_path);
Expand Down Expand Up @@ -273,7 +273,7 @@ pub async fn delete_pet(configuration: &configuration::Configuration, params: De
}
}

/// Multiple status values can be provided with comma separated strings
/// Multiple status values can be provided with comma separated strings. This is also a multi-line description to test rust doc comments
pub async fn find_pets_by_status(configuration: &configuration::Configuration, params: FindPetsByStatusParams) -> Result<ResponseContent<FindPetsByStatusSuccess>, Error<FindPetsByStatusError>> {

let uri_str = format!("{}/pet/findByStatus", configuration.base_path);
Expand Down
4 changes: 2 additions & 2 deletions samples/client/petstore/rust/reqwest/petstore-awsv4signature/docs/PetApi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Method | HTTP request | Description
> models::Pet add_pet(pet)
Add a new pet to the store


This is the description for the addPet operation

### Parameters

Expand Down Expand Up @@ -81,7 +81,7 @@ Name | Type | Description | Required | Notes
> Vec<models::Pet> find_pets_by_status(status, r#type)
Finds Pets by status

Multiple status values can be provided with comma separated strings
Multiple status values can be provided with comma separated strings. This is also a multi-line description to test rust doc comments

### Parameters

Expand Down
Loading
Loading