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

Author: ranger-ross

modules/openapi-generator/src/main/resources/rust/reqwest-trait/api.mustache

@@ -18,6 +18,12 @@ use super::{Error, configuration};
 pub trait {{{classname}}}: Send + Sync {
 {{#operations}}
 {{#operation}}
+
+    /// {{{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}}

modules/openapi-generator/src/test/resources/3_0/rust/petstore.yaml

@@ -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':
@@ -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

samples/client/petstore/rust/hyper/petstore/docs/PetApi.md

@@ -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
 
@@ -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
 

samples/client/petstore/rust/hyper0x/petstore/docs/PetApi.md

@@ -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
 
@@ -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
 

samples/client/petstore/rust/reqwest-trait/petstore/docs/PetApi.md

@@ -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
 
@@ -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
 

samples/client/petstore/rust/reqwest-trait/petstore/src/apis/fake_api.rs

@@ -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>>;
 }
 

samples/client/petstore/rust/reqwest-trait/petstore/src/apis/pet_api.rs

@@ -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>>;
 }
 
@@ -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;
 
@@ -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;
 

samples/client/petstore/rust/reqwest-trait/petstore/src/apis/store_api.rs

@@ -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>>;
 }
 

samples/client/petstore/rust/reqwest-trait/petstore/src/apis/testing_api.rs

@@ -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>>;
 }
 

samples/client/petstore/rust/reqwest-trait/petstore/src/apis/user_api.rs

@@ -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>>;
 }