doc: Documentation for customer and MCA and Mechant account API (#416)

Co-authored-by: bernard-eugine <114725419+bernard-eugine@users.noreply.github.com>

crates/router/src/openapi.rs

@@ -53,6 +53,11 @@ Never share your secret api keys. Keep them guarded and secure.
         crate::types::api::refunds::RefundResponse,
         crate::types::api::refunds::RefundStatus,
         crate::types::api::admin::CreateMerchantAccount,
+        crate::types::api::admin::DeleteResponse,
+        crate::types::api::admin::DeleteMcaResponse,
+        crate::types::api::customers::CustomerRequest,
+        crate::types::api::customers::CustomerDeleteResponse,
+        api_models::customers::CustomerResponse,
         api_models::enums::RoutingAlgorithm,
         api_models::enums::PaymentMethodType,
         api_models::enums::PaymentMethodSubType,

crates/router/src/routes/admin.rs

@@ -21,7 +21,6 @@ use crate::{
     )
 )]
 #[instrument(skip_all, fields(flow = ?Flow::MerchantsAccountCreate))]
-// #[post("")]
 pub async fn merchant_account_create(
     state: web::Data<AppState>,
     req: HttpRequest,
@@ -37,8 +36,18 @@ pub async fn merchant_account_create(
     .await
 }
 
+/// Merchant Account - Retrieve
+/// Retrieve a merchant account details.
+#[utoipa::path(
+    get,
+    path = "/account/{account_id}",
+    params (("account_id" = String, Path, description = "The unique identifier for the merchant account")),
+    responses(
+        (status = 200, description = "Merchant Account Retrieved", body = MerchantAccountResponse),
+        (status = 404, description = "Merchant account not found")
+    )
+)]
 #[instrument(skip_all, fields(flow = ?Flow::MerchantsAccountRetrieve))]
-// #[get("/{id}")]
 pub async fn retrieve_merchant_account(
     state: web::Data<AppState>,
     req: HttpRequest,
@@ -58,8 +67,19 @@ pub async fn retrieve_merchant_account(
     .await
 }
 
+/// Merchant Account - Update
+/// Update a merchant account details.
+#[utoipa::path(
+    post,
+    path = "/account/{account_id}",
+    request_body = CreateMerchantAccount,
+    params (("account_id" = String, Path, description = "The unique identifier for the merchant account")),
+    responses(
+        (status = 200, description = "Merchant Account Updated", body = MerchantAccountResponse),
+        (status = 404, description = "Merchant account not found")
+    )
+)]
 #[instrument(skip_all, fields(flow = ?Flow::MerchantsAccountUpdate))]
-// #[post["/{id}"]]
 pub async fn update_merchant_account(
     state: web::Data<AppState>,
     req: HttpRequest,
@@ -77,6 +97,17 @@ pub async fn update_merchant_account(
     .await
 }
 
+/// Merchant Account - Delete
+/// Delete a merchant account details.
+#[utoipa::path(
+    delete,
+    path = "/account/{account_id}",
+    params (("account_id" = String, Path, description = "The unique identifier for the merchant account")),
+    responses(
+        (status = 200, description = "Merchant Account Deleted", body = DeleteResponse),
+        (status = 404, description = "Merchant account not found")
+    )
+)]
 #[instrument(skip_all, fields(flow = ?Flow::MerchantsAccountDelete))]
 // #[delete("/{id}")]
 pub async fn delete_merchant_account(
@@ -128,8 +159,23 @@ pub async fn payment_connector_create(
     .await
 }
 
+/// Payment Connector - Retrieve
+///
+/// Retrieve Payment Connector Details
+#[utoipa::path(
+    get,
+    path = "/account/{account_id}/connectors/{connector_id}",
+    params(
+        ("account_id" = String, Path, description = "The unique identifier for the merchant account"),
+        ("connector_id" = i32, Path, description = "The unique identifier for the payment connector")
+    ),
+    responses(
+        (status = 200, description = "Payment Connector retrieved successfully", body = PaymentConnectorCreate),
+        (status = 404, description = "Payment Connector does not exist in records"),
+        (status = 401, description = "Unauthorized request")
+    )
+)]
 #[instrument(skip_all, fields(flow = ?Flow::PaymentConnectorsRetrieve))]
-// #[get("/{merchant_id}/connectors/{merchant_connector_id}")]
 pub async fn payment_connector_retrieve(
     state: web::Data<AppState>,
     req: HttpRequest,
@@ -153,8 +199,22 @@ pub async fn payment_connector_retrieve(
     .await
 }
 
+/// Payment Connector - List
+///
+/// List Payment Connector Details for the merchant
+#[utoipa::path(
+    get,
+    path = "/account/{account_id}/connectors",
+    params(
+        ("account_id" = String, Path, description = "The unique identifier for the merchant account"),
+    ),
+    responses(
+        (status = 200, description = "Payment Connector list retrieved successfully", body = Vec<PaymentConnectorCreate>),
+        (status = 404, description = "Payment Connector does not exist in records"),
+        (status = 401, description = "Unauthorized request")
+    )
+)]
 #[instrument(skip_all, fields(flow = ?Flow::PaymentConnectorsList))]
-
 pub async fn payment_connector_list(
     state: web::Data<AppState>,
     req: HttpRequest,
@@ -171,8 +231,24 @@ pub async fn payment_connector_list(
     .await
 }
 
+/// Payment Connector - Update
+///
+/// To update an existing Payment Connector. Helpful in enabling / disabling different payment methods and other settings for the connector etc
+#[utoipa::path(
+    post,
+    path = "/account/{account_id}/connectors/{connector_id}",
+    request_body = PaymentConnectorCreate,
+    params(
+        ("account_id" = String, Path, description = "The unique identifier for the merchant account"),
+        ("connector_id" = i32, Path, description = "The unique identifier for the payment connector")
+    ),
+    responses(
+        (status = 200, description = "Payment Connector Updated", body = PaymentConnectorCreate),
+        (status = 404, description = "Payment Connector does not exist in records"),
+        (status = 401, description = "Unauthorized request")
+    )
+)]
 #[instrument(skip_all, fields(flow = ?Flow::PaymentConnectorsUpdate))]
-// #[post("/{merchant_id}/connectors/{merchant_connector_id}")]
 pub async fn payment_connector_update(
     state: web::Data<AppState>,
     req: HttpRequest,
@@ -192,8 +268,22 @@ pub async fn payment_connector_update(
     .await
 }
 
+/// Payment Connector - Delete
+/// Delete or Detach a Payment Connector from Merchant Account
+#[utoipa::path(
+    delete,
+    path = "/account/{account_id}/connectors/{connector_id}",
+    params(
+        ("account_id" = String, Path, description = "The unique identifier for the merchant account"),
+        ("connector_id" = i32, Path, description = "The unique identifier for the payment connector")
+    ),
+    responses(
+        (status = 200, description = "Payment Connector Deleted", body = DeleteMcaResponse),
+        (status = 404, description = "Payment Connector does not exist in records"),
+        (status = 401, description = "Unauthorized request")
+    )
+)]
 #[instrument(skip_all, fields(flow = ?Flow::PaymentConnectorsDelete))]
-// #[delete("/{merchant_id}/connectors/{merchant_connector_id}")]
 pub async fn payment_connector_delete(
     state: web::Data<AppState>,
     req: HttpRequest,

crates/router/src/routes/customers.rs

@@ -8,8 +8,19 @@ use crate::{
     types::api::customers,
 };
 
+/// Create Customer
+///
+/// Create a customer object and store the customer details to be reused for future payments. Incase the customer already exists in the system, this API will respond with the customer details.
+#[utoipa::path(
+    post,
+    path = "/customers",
+    request_body = CustomerRequest,
+    responses(
+        (status = 200, description = "Customer Created", body = CustomerResponse),
+        (status = 400, description = "Invalid data")
+    )
+)]
 #[instrument(skip_all, fields(flow = ?Flow::CustomersCreate))]
-// #[post("")]
 pub async fn customers_create(
     state: web::Data<AppState>,
     req: HttpRequest,
@@ -25,8 +36,19 @@ pub async fn customers_create(
     .await
 }
 
+/// Retrieve Customer
+///
+/// Retrieve a customer's details.
+#[utoipa::path(
+    get,
+    path = "/customers/{customer_id}",
+    params (("customer_id" = String, Path, description = "The unique identifier for the Customer")),
+    responses(
+        (status = 200, description = "Customer Retrieved", body = CustomerResponse),
+        (status = 404, description = "Customer was not found")
+    )
+)]
 #[instrument(skip_all, fields(flow = ?Flow::CustomersRetrieve))]
-// #[get("/{customer_id}")]
 pub async fn customers_retrieve(
     state: web::Data<AppState>,
     req: HttpRequest,
@@ -53,8 +75,20 @@ pub async fn customers_retrieve(
     .await
 }
 
+/// Update Customer
+///
+/// Updates the customer's details in a customer object.
+#[utoipa::path(
+    post,
+    path = "/customers/{customer_id}",
+    request_body = CustomerRequest,
+    params (("customer_id" = String, Path, description = "The unique identifier for the Customer")),
+    responses(
+        (status = 200, description = "Customer was Updated", body = CustomerResponse),
+        (status = 404, description = "Customer was not found")
+    )
+)]
 #[instrument(skip_all, fields(flow = ?Flow::CustomersUpdate))]
-// #[post("/{customer_id}")]
 pub async fn customers_update(
     state: web::Data<AppState>,
     req: HttpRequest,
@@ -73,8 +107,19 @@ pub async fn customers_update(
     .await
 }
 
+/// Delete Customer
+///
+/// Delete a customer record.
+#[utoipa::path(
+    delete,
+    path = "/customers/{customer_id}",
+    params (("customer_id" = String, Path, description = "The unique identifier for the Customer")),
+    responses(
+        (status = 200, description = "Customer was Deleted", body = CustomerDeleteResponse),
+        (status = 404, description = "Customer was not found")
+    )
+)]
 #[instrument(skip_all, fields(flow = ?Flow::CustomersDelete))]
-// #[delete("/{customer_id}")]
 pub async fn customers_delete(
     state: web::Data<AppState>,
     req: HttpRequest,
@@ -88,7 +133,6 @@ pub async fn customers_delete(
 }
 
 #[instrument(skip_all, fields(flow = ?Flow::CustomersGetMandates))]
-// #[get("/{customer_id}/mandates")]
 pub async fn get_customer_mandates(
     state: web::Data<AppState>,
     req: HttpRequest,