docs: request and response in refund routes (#423)

crates/api_models/src/refunds.rs

@@ -82,22 +82,29 @@ pub struct RefundResponse {
     pub updated_at: Option<PrimitiveDateTime>,
 }
 
-#[derive(Debug, Clone, Eq, PartialEq, Deserialize, Serialize)]
+#[derive(Debug, Clone, Eq, PartialEq, Deserialize, Serialize, ToSchema)]
 pub struct RefundListRequest {
+    /// The identifier for the payment
     pub payment_id: Option<String>,
+    /// Limit on the number of objects to return
     pub limit: Option<i64>,
+    /// The time at which refund is created
     #[serde(default, with = "custom_serde::iso8601::option")]
     pub created: Option<PrimitiveDateTime>,
+    /// Time less than the refund created time
     #[serde(default, rename = "created.lt", with = "custom_serde::iso8601::option")]
     pub created_lt: Option<PrimitiveDateTime>,
+    /// Time greater than the refund created time
     #[serde(default, rename = "created.gt", with = "custom_serde::iso8601::option")]
     pub created_gt: Option<PrimitiveDateTime>,
+    /// Time less than or equals to the refund created time
     #[serde(
         default,
         rename = "created.lte",
         with = "custom_serde::iso8601::option"
     )]
     pub created_lte: Option<PrimitiveDateTime>,
+    /// Time greater than or equals to the refund created time
     #[serde(
         default,
         rename = "created.gte",

crates/router/src/openapi.rs

@@ -52,6 +52,7 @@ Never share your secret api keys. Keep them guarded and secure.
         crate::types::api::refunds::RefundType,
         crate::types::api::refunds::RefundResponse,
         crate::types::api::refunds::RefundStatus,
+        crate::types::api::refunds::RefundUpdateRequest,
         crate::types::api::admin::CreateMerchantAccount,
         crate::types::api::admin::DeleteResponse,
         crate::types::api::admin::DeleteMcaResponse,
@@ -112,6 +113,7 @@ Never share your secret api keys. Keep them guarded and secure.
         api_models::payments::PaymentsCancelRequest,
         api_models::payments::PaymentListConstraints,
         api_models::payments::PaymentListResponse,
+        api_models::refunds::RefundListRequest,
         crate::types::api::admin::MerchantAccountResponse,
         crate::types::api::admin::MerchantConnectorId,
         crate::types::api::admin::MerchantDetails,

crates/router/src/routes/refunds.rs

@@ -37,6 +37,20 @@ pub async fn refunds_create(
     .await
 }
 
+/// Refunds - Retrieve
+///
+/// To retrieve a refund against an already processed payment
+#[utoipa::path(
+    get,
+    path = "/refunds/{refund_id}",
+    params(
+        ("refund_id" = String, Path, description = "The identifier for refund")
+    ),
+    responses(
+        (status = 200, description = "Refund retrieved", body = RefundResponse),
+        (status = 404, description = "Refund does not exist in our records")
+    )
+)]
 #[instrument(skip_all, fields(flow = ?Flow::RefundsRetrieve))]
 // #[get("/{id}")]
 pub async fn refunds_retrieve(
@@ -58,6 +72,21 @@ pub async fn refunds_retrieve(
     .await
 }
 
+/// Refunds - Update
+///
+/// To update a refund against an already processed payment
+#[utoipa::path(
+    post,
+    path = "/refunds/{refund_id}",
+    params(
+        ("refund_id" = String, Path, description = "The identifier for refund")
+    ),
+    request_body=RefundUpdateRequest,
+    responses(
+        (status = 200, description = "Refund updated", body = RefundResponse),
+        (status = 400, description = "Missing Mandatory fields")
+    )
+)]
 #[instrument(skip_all, fields(flow = ?Flow::RefundsUpdate))]
 // #[post("/{id}")]
 pub async fn refunds_update(
@@ -79,6 +108,26 @@ pub async fn refunds_update(
     .await
 }
 
+/// Refunds - List
+///
+/// To list the refunds associated with a payment_id or with the merchant, if payment_id is not provided
+#[utoipa::path(
+    get,
+    path = "/refunds/list",
+    params(
+        ("payment_id" = String, Query, description = "The identifier for the payment"),
+        ("limit" = i64, Query, description = "Limit on the number of objects to return"),
+        ("created" = PrimitiveDateTime, Query, description = "The time at which refund is created"),
+        ("created_lt" = PrimitiveDateTime, Query, description = "Time less than the refund created time"),
+        ("created_gt" = PrimitiveDateTime, Query, description = "Time greater than the refund created time"),
+        ("created_lte" = PrimitiveDateTime, Query, description = "Time less than or equals to the refund created time"),
+        ("created_gte" = PrimitiveDateTime, Query, description = "Time greater than or equals to the refund created time")
+    ),
+    responses(
+        (status = 200, description = "List of refunds", body = RefundListResponse),
+        (status = 404, description = "Refund does not exist in our records")
+    )
+)]
 #[instrument(skip_all, fields(flow = ?Flow::RefundsList))]
 #[cfg(feature = "olap")]
 // #[get("/list")]

openapi/generated.json

@@ -2086,6 +2086,45 @@
           }
         }
       },
+      "RefundListRequest": {
+        "type": "object",
+        "properties": {
+          "payment_id": {
+            "type": "string",
+            "description": "The identifier for the payment"
+          },
+          "limit": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Limit on the number of objects to return"
+          },
+          "created": {
+            "type": "string",
+            "format": "date-time",
+            "description": "The time at which refund is created"
+          },
+          "created.lt": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Time less than the refund created time"
+          },
+          "created.gt": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Time greater than the refund created time"
+          },
+          "created.lte": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Time less than or equals to the refund created time"
+          },
+          "created.gte": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Time greater than or equals to the refund created time"
+          }
+        }
+      },
       "RefundRequest": {
         "type": "object",
         "required": [
@@ -2194,6 +2233,20 @@
           "instant"
         ]
       },
+      "RefundUpdateRequest": {
+        "type": "object",
+        "properties": {
+          "reason": {
+            "type": "string",
+            "description": "An arbitrary string attached to the object. Often useful for displaying to users and your customer support executive",
+            "example": "Customer returned the product",
+            "maxLength": 255
+          },
+          "metadata": {
+            "type": "object"
+          }
+        }
+      },
       "RoutingAlgorithm": {
         "type": "string",
         "description": "The routing algorithm to be used to process the incoming request from merchant to outgoing payment processor or payment method. The default is 'Custom'",