refactor(payouts): openAPI schemas and mintlify docs (#5284)

Co-authored-by: hyperswitch-bot[bot] <148525504+hyperswitch-bot[bot]@users.noreply.github.com>
Co-authored-by: Narayan Bhat <48803246+Narayanbhat166@users.noreply.github.com>
Co-authored-by: Vrishab Srivatsa <136090360+vsrivatsa-juspay@users.noreply.github.com>
Co-authored-by: Prajjwal Kumar <prajjwal.kumar@juspay.in>

crates/openapi/src/openapi.rs

@@ -172,8 +172,9 @@ Never share your secret api keys. Keep them guarded and secure.
         routes::payouts::payouts_cancel,
         routes::payouts::payouts_fulfill,
         routes::payouts::payouts_list,
-        routes::payouts::payouts_filter,
         routes::payouts::payouts_confirm,
+        routes::payouts::payouts_list_filters,
+        routes::payouts::payouts_list_by_filter,
 
         // Routes for api keys
         routes::api_keys::api_key_create,
@@ -479,16 +480,19 @@ Never share your secret api keys. Keep them guarded and secure.
         api_models::payouts::BacsBankTransfer,
         api_models::payouts::SepaBankTransfer,
         api_models::payouts::PixBankTransfer,
-        api_models::payouts::PayoutRequest,
+        api_models::payouts::PayoutsCreateRequest,
+        api_models::payouts::PayoutUpdateRequest,
+        api_models::payouts::PayoutConfirmRequest,
+        api_models::payouts::PayoutCancelRequest,
+        api_models::payouts::PayoutFulfillRequest,
+        api_models::payouts::PayoutRetrieveRequest,
         api_models::payouts::PayoutAttemptResponse,
-        api_models::payouts::PayoutActionRequest,
-        api_models::payouts::PayoutCreateRequest,
         api_models::payouts::PayoutCreateResponse,
         api_models::payouts::PayoutListConstraints,
+        api_models::payouts::PayoutListFilters,
         api_models::payouts::PayoutListFilterConstraints,
         api_models::payouts::PayoutListResponse,
         api_models::payouts::PayoutRetrieveBody,
-        api_models::payouts::PayoutRetrieveRequest,
         api_models::payouts::PayoutMethodData,
         api_models::payouts::PayoutLinkResponse,
         api_models::payouts::Bank,

crates/openapi/src/routes/payouts.rs

@@ -2,7 +2,7 @@
 #[utoipa::path(
     post,
     path = "/payouts/create",
-    request_body=PayoutCreateRequest,
+    request_body=PayoutsCreateRequest,
     responses(
         (status = 200, description = "Payout created", body = PayoutCreateResponse),
         (status = 400, description = "Missing Mandatory fields")
@@ -18,7 +18,8 @@ pub async fn payouts_create() {}
     get,
     path = "/payouts/{payout_id}",
     params(
-        ("payout_id" = String, Path, description = "The identifier for payout]")
+        ("payout_id" = String, Path, description = "The identifier for payout"),
+        ("force_sync" = Option<bool>, Query, description = "Sync with the connector to get the payout details (defaults to false)")
     ),
     responses(
         (status = 200, description = "Payout retrieved", body = PayoutCreateResponse),
@@ -35,9 +36,9 @@ pub async fn payouts_retrieve() {}
     post,
     path = "/payouts/{payout_id}",
     params(
-        ("payout_id" = String, Path, description = "The identifier for payout]")
+        ("payout_id" = String, Path, description = "The identifier for payout")
     ),
-    request_body=PayoutCreateRequest,
+    request_body=PayoutUpdateRequest,
     responses(
         (status = 200, description = "Payout updated", body = PayoutCreateResponse),
         (status = 400, description = "Missing Mandatory fields")
@@ -55,7 +56,7 @@ pub async fn payouts_update() {}
     params(
         ("payout_id" = String, Path, description = "The identifier for payout")
     ),
-    request_body=PayoutActionRequest,
+    request_body=PayoutCancelRequest,
     responses(
         (status = 200, description = "Payout cancelled", body = PayoutCreateResponse),
         (status = 400, description = "Missing Mandatory fields")
@@ -73,7 +74,7 @@ pub async fn payouts_cancel() {}
     params(
         ("payout_id" = String, Path, description = "The identifier for payout")
     ),
-    request_body=PayoutActionRequest,
+    request_body=PayoutFulfillRequest,
     responses(
         (status = 200, description = "Payout fulfilled", body = PayoutCreateResponse),
         (status = 400, description = "Missing Mandatory fields")
@@ -88,38 +89,61 @@ pub async fn payouts_fulfill() {}
 #[utoipa::path(
     get,
     path = "/payouts/list",
+    params(
+        ("customer_id" = String, Query, description = "The identifier for customer"),
+        ("starting_after" = String, Query, description = "A cursor for use in pagination, fetch the next list after some object"),
+        ("ending_before" = String, Query, description = "A cursor for use in pagination, fetch the previous list before some object"),
+        ("limit" = String, Query, description = "limit on the number of objects to return"),
+        ("created" = String, Query, description = "The time at which payout is created"),
+        ("time_range" = String, Query, description = "The time range for which objects are needed. TimeRange has two fields start_time and end_time from which objects can be filtered as per required scenarios (created_at, time less than, greater than etc).")
+    ),
     responses(
         (status = 200, description = "Payouts listed", body = PayoutListResponse),
         (status = 404, description = "Payout not found")
     ),
     tag = "Payouts",
-    operation_id = "List payouts",
+    operation_id = "List payouts using generic constraints",
     security(("api_key" = []))
 )]
 pub async fn payouts_list() {}
 
-/// Payouts - Filter
+/// Payouts - List available filters
+#[utoipa::path(
+    post,
+    path = "/payouts/filter",
+    request_body=TimeRange,
+    responses(
+        (status = 200, description = "Filters listed", body = PayoutListFilters)
+    ),
+    tag = "Payouts",
+    operation_id = "List available payout filters",
+    security(("api_key" = []))
+)]
+pub async fn payouts_list_filters() {}
+
+/// Payouts - List using filters
 #[utoipa::path(
     post,
     path = "/payouts/list",
+    request_body=PayoutListFilterConstraints,
     responses(
         (status = 200, description = "Payouts filtered", body = PayoutListResponse),
         (status = 404, description = "Payout not found")
     ),
     tag = "Payouts",
-    operation_id = "Filter payouts",
+    operation_id = "Filter payouts using specific constraints",
     security(("api_key" = []))
 )]
-pub async fn payouts_filter() {}
+pub async fn payouts_list_by_filter() {}
 
 /// Payouts - Confirm
 #[utoipa::path(
     post,
     path = "/payouts/{payout_id}/confirm",
     params(
-        ("payout_id" = String, Path, description = "The identifier for payout]")
+        ("payout_id" = String, Path, description = "The identifier for payout")
     ),
-    request_body=PayoutCreateRequest,
+    request_body=PayoutConfirmRequest,
     responses(
         (status = 200, description = "Payout updated", body = PayoutCreateResponse),
         (status = 400, description = "Missing Mandatory fields")