From 2bc8756e061e9e0e705ce2c6b533c3583f3efa8b Mon Sep 17 00:00:00 2001 From: Sai Harsha Vardhan <56996463+sai-harsha-vardhan@users.noreply.github.com> Date: Wed, 18 Sep 2024 12:24:55 +0530 Subject: [PATCH] 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 | 221 +++++++++++++++++++++++++ crates/openapi/src/openapi_v2.rs | 7 + crates/openapi/src/routes/customers.rs | 111 +++++++++++++ 3 files changed, 339 insertions(+) diff --git a/api-reference-v2/openapi_spec.json b/api-reference-v2/openapi_spec.json index 117c9d2e9e..9db2fcfdfd 100644 --- a/api-reference-v2/openapi_spec.json +++ b/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": { diff --git a/crates/openapi/src/openapi_v2.rs b/crates/openapi/src/openapi_v2.rs index f2a920cdb9..8a21110ae8 100644 --- a/crates/openapi/src/openapi_v2.rs +++ b/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, diff --git a/crates/openapi/src/routes/customers.rs b/crates/openapi/src/routes/customers.rs index 2794ee7310..26140252eb 100644 --- a/crates/openapi/src/routes/customers.rs +++ b/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), + (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() {}