docs: add openapi docs for customers v2 (#5926)

Co-authored-by: hyperswitch-bot[bot] <148525504+hyperswitch-bot[bot]@users.noreply.github.com>

api-reference-v2/openapi_spec.json

@@ -1432,6 +1432,227 @@
           }
         ]
       }
+    },
+    "/v2/customers": {
+      "post": {
+        "tags": [
+          "Customers"
+        ],
+        "summary": "Creates a customer object and stores the customer details to be reused for future payments.",
+        "description": "Incase the customer already exists in the system, this API will respond with the customer details.",
+        "operationId": "Create a Customer",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CustomerRequest"
+              },
+              "examples": {
+                "Create a customer with name and email": {
+                  "value": {
+                    "email": "guest@example.com",
+                    "name": "John Doe"
+                  }
+                }
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "Customer Created",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CustomerResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid data"
+          }
+        },
+        "security": [
+          {
+            "api_key": []
+          }
+        ]
+      }
+    },
+    "/v2/customers/{id}": {
+      "get": {
+        "tags": [
+          "Customers"
+        ],
+        "summary": "Customers - Retrieve",
+        "description": "Retrieves a customer's details.",
+        "operationId": "Retrieve a Customer",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "description": "The unique identifier for the Customer",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Customer Retrieved",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CustomerResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Customer was not found"
+          }
+        },
+        "security": [
+          {
+            "api_key": []
+          },
+          {
+            "ephemeral_key": []
+          }
+        ]
+      },
+      "post": {
+        "tags": [
+          "Customers"
+        ],
+        "summary": "Customers - Update",
+        "description": "Updates the customer's details in a customer object.",
+        "operationId": "Update a Customer",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "description": "The unique identifier for the Customer",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CustomerRequest"
+              },
+              "examples": {
+                "Update name and email of a customer": {
+                  "value": {
+                    "email": "guest@example.com",
+                    "name": "John Doe"
+                  }
+                }
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "Customer was Updated",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CustomerResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Customer was not found"
+          }
+        },
+        "security": [
+          {
+            "api_key": []
+          }
+        ]
+      },
+      "delete": {
+        "tags": [
+          "Customers"
+        ],
+        "summary": "Customers - Delete",
+        "description": "Delete a customer record.",
+        "operationId": "Delete a Customer",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "description": "The unique identifier for the Customer",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Customer was Deleted",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CustomerDeleteResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Customer was not found"
+          }
+        },
+        "security": [
+          {
+            "api_key": []
+          }
+        ]
+      }
+    },
+    "/v2/customers/list": {
+      "post": {
+        "tags": [
+          "Customers"
+        ],
+        "summary": "Customers - List",
+        "description": "Lists all the customers for a particular merchant id.",
+        "operationId": "List all Customers for a Merchant",
+        "responses": {
+          "200": {
+            "description": "Customers retrieved",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/components/schemas/CustomerResponse"
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid Data"
+          }
+        },
+        "security": [
+          {
+            "api_key": []
+          }
+        ]
+      }
     }
   },
   "components": {

crates/openapi/src/openapi_v2.rs

@@ -109,6 +109,13 @@ Never share your secret api keys. Keep them guarded and secure.
         routes::api_keys::api_key_retrieve,
         routes::api_keys::api_key_update,
         routes::api_keys::api_key_revoke,
+
+        //Routes for customers
+        routes::customers::customers_create,
+        routes::customers::customers_retrieve,
+        routes::customers::customers_update,
+        routes::customers::customers_delete,
+        routes::customers::customers_list,
     ),
     components(schemas(
         common_utils::types::MinorUnit,

crates/openapi/src/routes/customers.rs

@@ -23,6 +23,7 @@
     operation_id = "Create a Customer",
     security(("api_key" = []))
 )]
+#[cfg(feature = "v1")]
 pub async fn customers_create() {}
 
 /// Customers - Retrieve
@@ -40,6 +41,7 @@ pub async fn customers_create() {}
     operation_id = "Retrieve a Customer",
     security(("api_key" = []), ("ephemeral_key" = []))
 )]
+#[cfg(feature = "v1")]
 pub async fn customers_retrieve() {}
 
 /// Customers - Update
@@ -66,6 +68,7 @@ pub async fn customers_retrieve() {}
     operation_id = "Update a Customer",
     security(("api_key" = []))
 )]
+#[cfg(feature = "v1")]
 pub async fn customers_update() {}
 
 /// Customers - Delete
@@ -83,6 +86,7 @@ pub async fn customers_update() {}
     operation_id = "Delete a Customer",
     security(("api_key" = []))
 )]
+#[cfg(feature = "v1")]
 pub async fn customers_delete() {}
 
 /// Customers - List
@@ -99,4 +103,111 @@ pub async fn customers_delete() {}
     operation_id = "List all Customers for a Merchant",
     security(("api_key" = []))
 )]
+#[cfg(feature = "v1")]
+pub async fn customers_list() {}
+
+/// Creates a customer object and stores 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 = "/v2/customers",
+    request_body  (
+        content = CustomerRequest,
+        examples  (( "Create a customer with name and email" =(
+        value =json!( {
+            "email": "guest@example.com",
+            "name": "John Doe"
+        })
+        )))
+    ),
+    responses(
+        (status = 200, description = "Customer Created", body = CustomerResponse),
+        (status = 400, description = "Invalid data")
+
+    ),
+    tag = "Customers",
+    operation_id = "Create a Customer",
+    security(("api_key" = []))
+)]
+#[cfg(feature = "v2")]
+pub async fn customers_create() {}
+
+/// Customers - Retrieve
+///
+/// Retrieves a customer's details.
+#[utoipa::path(
+    get,
+    path = "/v2/customers/{id}",
+    params (("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")
+    ),
+    tag = "Customers",
+    operation_id = "Retrieve a Customer",
+    security(("api_key" = []), ("ephemeral_key" = []))
+)]
+#[cfg(feature = "v2")]
+pub async fn customers_retrieve() {}
+
+/// Customers - Update
+///
+/// Updates the customer's details in a customer object.
+#[utoipa::path(
+    post,
+    path = "/v2/customers/{id}",
+    request_body (
+        content = CustomerRequest,
+        examples  (( "Update name and email of a customer" =(
+        value =json!( {
+            "email": "guest@example.com",
+            "name": "John Doe"
+        })
+        )))
+    ),
+    params (("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")
+    ),
+    tag = "Customers",
+    operation_id = "Update a Customer",
+    security(("api_key" = []))
+)]
+#[cfg(feature = "v2")]
+pub async fn customers_update() {}
+
+/// Customers - Delete
+///
+/// Delete a customer record.
+#[utoipa::path(
+    delete,
+    path = "/v2/customers/{id}",
+    params (("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")
+    ),
+    tag = "Customers",
+    operation_id = "Delete a Customer",
+    security(("api_key" = []))
+)]
+#[cfg(feature = "v2")]
+pub async fn customers_delete() {}
+
+/// Customers - List
+///
+/// Lists all the customers for a particular merchant id.
+#[utoipa::path(
+    post,
+    path = "/v2/customers/list",
+    responses(
+        (status = 200, description = "Customers retrieved", body = Vec<CustomerResponse>),
+        (status = 400, description = "Invalid Data"),
+    ),
+    tag = "Customers",
+    operation_id = "List all Customers for a Merchant",
+    security(("api_key" = []))
+)]
+#[cfg(feature = "v2")]
 pub async fn customers_list() {}