rust/hyperswitch
1
0
Fork 0
mirror of https://github.com/juspay/hyperswitch.git synced 2025-10-29 17:19:15 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(subscription): add open api specs (#9884)

Browse Source
This commit is contained in:
Jagan
2025-10-17 19:24:19 +05:30
committed by GitHub
parent db7228aed2
commit b42fbdb50f
5 changed files with 1668 additions and 87 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
crates/openapi/src/openapi.rs
View File

@ -66,7 +66,8 @@ Never share your secret api keys. Keep them guarded and secure.
(name = "payment link", description = "Create payment link"),
(name = "Routing", description = "Create and manage routing configurations"),
(name = "Event", description = "Manage events"),
(name = "Authentication", description = "Create and manage authentication")
(name = "Authentication", description = "Create and manage authentication"),
(name = "Subscriptions", description = "Subscription management and billing endpoints")
),
// The paths will be displayed in the same order as they are registered here
paths(
@ -222,6 +223,15 @@ Never share your secret api keys. Keep them guarded and secure.
// Routes for platform account
routes::platform::create_platform_account,
//Routes for subscriptions
routes::subscriptions::create_and_confirm_subscription,
routes::subscriptions::create_subscription,
routes::subscriptions::confirm_subscription,
routes::subscriptions::get_subscription,
routes::subscriptions::update_subscription,
routes::subscriptions::get_subscription_plans,
routes::subscriptions::get_estimate,
),
components(schemas(
common_utils::types::MinorUnit,
@ -876,6 +886,31 @@ Never share your secret api keys. Keep them guarded and secure.
api_models::open_router::PriorityLogicData,
api_models::user::PlatformAccountCreateRequest,
api_models::user::PlatformAccountCreateResponse,
common_utils::id_type::CustomerId,
common_utils::id_type::SubscriptionId,
common_utils::id_type::MerchantId,
common_utils::id_type::InvoiceId,
common_utils::id_type::MerchantConnectorAccountId,
api_models::enums::connector_enums::InvoiceStatus,
api_models::subscription::ClientSecret,
api_models::subscription::CreateAndConfirmSubscriptionRequest,
api_models::subscription::CreateSubscriptionRequest,
api_models::subscription::ConfirmSubscriptionRequest,
api_models::subscription::UpdateSubscriptionRequest,
api_models::subscription::SubscriptionResponse,
api_models::subscription::GetPlansResponse,
api_models::subscription::EstimateSubscriptionResponse,
api_models::subscription::GetPlansQuery,
api_models::subscription::EstimateSubscriptionQuery,
api_models::subscription::ConfirmSubscriptionPaymentDetails,
api_models::subscription::PaymentDetails,
api_models::subscription::CreateSubscriptionPaymentDetails,
api_models::subscription::SubscriptionLineItem,
api_models::subscription::SubscriptionPlanPrices,
api_models::subscription::PaymentResponseData,
api_models::subscription::Invoice,
api_models::subscription::SubscriptionStatus,
api_models::subscription::PeriodUnit,
)),
modifiers(&SecurityAddon)
)]

1
crates/openapi/src/routes.rs
View File

@ -23,6 +23,7 @@ pub mod refunds;
pub mod relay;
pub mod revenue_recovery;
pub mod routing;
pub mod subscriptions;
pub mod three_ds_decision_rule;
pub mod tokenization;
pub mod webhook_events;

208
crates/openapi/src/routes/subscriptions.rs Normal file
View File

@ -0,0 +1,208 @@
use serde_json::json;
use utoipa;
/// Subscription - Create and Confirm
///
/// Creates and confirms a subscription in a single request.
#[utoipa::path(
post,
path = "/subscriptions",
request_body(
content = CreateAndConfirmSubscriptionRequest,
examples((
"Create and confirm subscription" = (
value = json!({
"customer_id": "cust_123456789",
"plan_id": "plan_monthly_basic",
"payment_method_id": "pm_1234567890",
"billing_details": {
"name": "John Doe",
"email": "john@example.com"
}
})
)
))
),
responses(
(status = 200, description = "Subscription created and confirmed successfully", body = SubscriptionResponse),
(status = 400, description = "Invalid subscription data"),
(status = 404, description = "Customer or plan not found")
),
params(
("X-Profile-Id" = String, Header, description = "Profile ID for authentication")
),
tag = "Subscriptions",
operation_id = "Create and Confirm Subscription",
security(("api_key" = []))
)]
pub async fn create_and_confirm_subscription() {}
/// Subscription - Create
///
/// Creates a subscription that requires separate confirmation.
#[utoipa::path(
post,
path = "/subscriptions/create",
request_body(
content = CreateSubscriptionRequest,
examples((
"Create subscription" = (
value = json!({
"customer_id": "cust_123456789",
"plan_id": "plan_monthly_basic",
"trial_days": 7,
"metadata": {
"source": "web_app"
}
})
)
))
),
responses(
(status = 200, description = "Subscription created successfully", body = SubscriptionResponse),
(status = 400, description = "Invalid subscription data"),
(status = 404, description = "Customer or plan not found")
),
params(
("X-Profile-Id" = String, Header, description = "Profile ID for authentication")
),
tag = "Subscriptions",
operation_id = "Create Subscription",
security(("api_key" = []))
)]
pub async fn create_subscription() {}
/// Subscription - Confirm
///
/// Confirms a previously created subscription.
#[utoipa::path(
post,
path = "/subscriptions/{subscription_id}/confirm",
params(
("subscription_id" = String, Path, description = "The unique identifier for the subscription"),
("X-Profile-Id" = String, Header, description = "Profile ID for authentication")
),
request_body(
content = ConfirmSubscriptionRequest,
examples((
"Confirm subscription" = (
value = json!({
"payment_method_id": "pm_1234567890",
"client_secret": "seti_1234567890_secret_abcdef",
"return_url": "https://example.com/return"
})
)
))
),
responses(
(status = 200, description = "Subscription confirmed successfully", body = SubscriptionResponse),
(status = 400, description = "Invalid confirmation data"),
(status = 404, description = "Subscription not found"),
(status = 409, description = "Subscription already confirmed")
),
tag = "Subscriptions",
operation_id = "Confirm Subscription",
security(("api_key" = []), ("client_secret" = []))
)]
pub async fn confirm_subscription() {}
/// Subscription - Retrieve
///
/// Retrieves subscription details by ID.
#[utoipa::path(
get,
path = "/subscriptions/{subscription_id}",
params(
("subscription_id" = String, Path, description = "The unique identifier for the subscription"),
("X-Profile-Id" = String, Header, description = "Profile ID for authentication")
),
responses(
(status = 200, description = "Subscription retrieved successfully", body = SubscriptionResponse),
(status = 404, description = "Subscription not found")
),
tag = "Subscriptions",
operation_id = "Retrieve Subscription",
security(("api_key" = []))
)]
pub async fn get_subscription() {}
/// Subscription - Update
///
/// Updates an existing subscription.
#[utoipa::path(
put,
path = "/subscriptions/{subscription_id}/update",
params(
("subscription_id" = String, Path, description = "The unique identifier for the subscription"),
("X-Profile-Id" = String, Header, description = "Profile ID for authentication")
),
request_body(
content = UpdateSubscriptionRequest,
examples((
"Update subscription" = (
value = json!({
"plan_id": "plan_yearly_premium",
"proration_behavior": "create_prorations",
"metadata": {
"updated_reason": "plan_upgrade"
}
})
)
))
),
responses(
(status = 200, description = "Subscription updated successfully", body = SubscriptionResponse),
(status = 400, description = "Invalid update data"),
(status = 404, description = "Subscription not found")
),
tag = "Subscriptions",
operation_id = "Update Subscription",
security(("api_key" = []))
)]
pub async fn update_subscription() {}
/// Subscription - Get Plans
///
/// Retrieves available subscription plans.
#[utoipa::path(
get,
path = "/subscriptions/plans",
params(
("X-Profile-Id" = String, Header, description = "Profile ID for authentication"),
("limit" = Option<u32>, Query, description = "Number of plans to retrieve"),
("offset" = Option<u32>, Query, description = "Number of plans to skip"),
("product_id" = Option<String>, Query, description = "Filter by product ID")
),
responses(
(status = 200, description = "Plans retrieved successfully", body = Vec<GetPlansResponse>),
(status = 400, description = "Invalid query parameters")
),
tag = "Subscriptions",
operation_id = "Get Subscription Plans",
security(("api_key" = []), ("client_secret" = []))
)]
pub async fn get_subscription_plans() {}
/// Subscription - Get Estimate
///
/// Gets pricing estimate for a subscription.
#[utoipa::path(
get,
path = "/subscriptions/estimate",
params(
("X-Profile-Id" = String, Header, description = "Profile ID for authentication"),
("plan_id" = String, Query, description = "Plan ID for estimation"),
("customer_id" = Option<String>, Query, description = "Customer ID for personalized pricing"),
("coupon_id" = Option<String>, Query, description = "Coupon ID to apply discount"),
("trial_days" = Option<u32>, Query, description = "Number of trial days")
),
responses(
(status = 200, description = "Estimate retrieved successfully", body = EstimateSubscriptionResponse),
(status = 400, description = "Invalid estimation parameters"),
(status = 404, description = "Plan not found")
),
tag = "Subscriptions",
operation_id = "Get Subscription Estimate",
security(("api_key" = []))
)]
pub async fn get_estimate() {}