document billing endpoints

crates/service/plugins/billing/src/stripe/http_endpoints/checkout/create/stripe_create_checkout_session_json_handler.rs

@@ -36,7 +36,7 @@ pub struct CreateCheckoutSessionSuccessResponse {
 /// Create a Stripe Checkout session and return the redirect URL in Json.
 #[utoipa::path(
   get,
-  tag = "Stripe Billing",
+  tag = "Billing",
   path = "/v1/billing/stripe/checkout/create_redirect",
   params(
     ("request" = CreateCheckoutSessionRequest, description = "Payload for Request"),

crates/service/plugins/billing/src/users/http_endpoints/list_active_user_subscriptions_handler.rs

@@ -1,6 +1,7 @@
 use actix_http::StatusCode;
 use actix_web::{HttpRequest, HttpResponse, ResponseError, web};
 use log::error;
+use utoipa::ToSchema;
 
 use http_server_common::response::serialize_as_json_error::serialize_as_json_error;
 
@@ -8,14 +9,14 @@ use crate::stripe::traits::internal_user_lookup::InternalUserLookup;
 
 // =============== Success Response ===============
 
-#[derive(Serialize)]
-pub struct SuccessResponse {
+#[derive(Serialize, ToSchema)]
+pub struct ListActiveUserSubscriptionsResponse {
   pub success: bool,
   pub maybe_loyalty_program: Option<String>,
   pub active_subscriptions: Vec<SubscriptionProductKey>,
 }
 
-#[derive(Serialize)]
+#[derive(Serialize, ToSchema)]
 pub struct SubscriptionProductKey {
   pub namespace: String,
   pub product_slug: String,
@@ -23,17 +24,17 @@ pub struct SubscriptionProductKey {
 
 // =============== Error Response ===============
 
-#[derive(Debug, Serialize, Eq, PartialEq, Copy, Clone)]
-pub enum EndpointError {
+#[derive(Debug, Serialize, Eq, PartialEq, Copy, Clone, ToSchema)]
+pub enum ListActiveUserSubscriptionsError {
   InvalidSession,
   ServerError,
 }
 
-impl ResponseError for EndpointError {
+impl ResponseError for ListActiveUserSubscriptionsError {
   fn status_code(&self) -> StatusCode {
     match *self {
-      EndpointError::InvalidSession => StatusCode::UNAUTHORIZED,
-      EndpointError::ServerError => StatusCode::INTERNAL_SERVER_ERROR,
+      ListActiveUserSubscriptionsError::InvalidSession => StatusCode::UNAUTHORIZED,
+      ListActiveUserSubscriptionsError::ServerError => StatusCode::INTERNAL_SERVER_ERROR,
     }
   }
 
@@ -43,32 +44,41 @@ impl ResponseError for EndpointError {
 }
 
 // NB: Not using derive_more::Display since Clion doesn't understand it.
-impl std::fmt::Display for EndpointError {
+impl std::fmt::Display for ListActiveUserSubscriptionsError {
   fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
     write!(f, "{:?}", self)
   }
 }
 
+#[utoipa::path(
+  get,
+  tag = "Billing",
+  path = "/v1/billing/active_subscriptions",
+  responses(
+    (status = 200, description = "Success response", body = ListActiveUserSubscriptionsResponse),
+    (status = 500, description = "Server error", body = ListActiveUserSubscriptionsError),
+  ),
+)]
 pub async fn list_active_user_subscriptions_handler(
   http_request: HttpRequest,
   internal_user_lookup: web::Data<dyn InternalUserLookup>,
-) -> Result<HttpResponse, EndpointError>
+) -> Result<HttpResponse, ListActiveUserSubscriptionsError>
 {
   let maybe_user_metadata = internal_user_lookup
       .lookup_user_from_http_request(&http_request)
       .await
       .map_err(|err| {
         error!("Error looking up user: {:?}", err);
-        EndpointError::ServerError // NB: This was probably *our* fault.
+        ListActiveUserSubscriptionsError::ServerError // NB: This was probably *our* fault.
       })?;
 
   // NB: Our integration relies on an internal user token being present.
   let user_metadata = match maybe_user_metadata {
-    None => return Err(EndpointError::InvalidSession),
+    None => return Err(ListActiveUserSubscriptionsError::InvalidSession),
     Some(user_metadata) => user_metadata,
   };
 
-  let response = SuccessResponse {
+  let response = ListActiveUserSubscriptionsResponse {
     success: true,
     maybe_loyalty_program: user_metadata.maybe_loyalty_program_key,
     active_subscriptions: user_metadata.existing_subscription_keys
@@ -81,7 +91,7 @@ pub async fn list_active_user_subscriptions_handler(
   };
 
   let body = serde_json::to_string(&response)
-      .map_err(|_e| EndpointError::ServerError)?;
+      .map_err(|_e| ListActiveUserSubscriptionsError::ServerError)?;
 
   Ok(HttpResponse::Ok()
       .content_type("application/json")

crates/service/web/storyteller_web/src/api_doc.rs

@@ -2,6 +2,7 @@ use utoipa::OpenApi;
 
 use billing_component::stripe::http_endpoints::checkout::create::stripe_create_checkout_session_error::CreateCheckoutSessionError;
 use billing_component::stripe::http_endpoints::checkout::create::stripe_create_checkout_session_json_handler::*;
+use billing_component::users::http_endpoints::list_active_user_subscriptions_handler::*;
 use enums::by_table::beta_keys::beta_key_product::BetaKeyProduct;
 use enums::by_table::comments::comment_entity_type::CommentEntityType;
 use enums::by_table::featured_items::featured_item_entity_type::FeaturedItemEntityType;
@@ -123,6 +124,7 @@ use crate::http_server::web_utils::response_success_helpers::*;
 #[openapi(
   paths(
     billing_component::stripe::http_endpoints::checkout::create::stripe_create_checkout_session_json_handler::stripe_create_checkout_session_json_handler,
+    billing_component::users::http_endpoints::list_active_user_subscriptions_handler::list_active_user_subscriptions_handler,
     crate::http_server::endpoints::analytics::log_browser_session_handler::log_browser_session_handler,
     crate::http_server::endpoints::beta_keys::create_beta_keys_handler::create_beta_keys_handler,
     crate::http_server::endpoints::beta_keys::edit_beta_key_distributed_flag_handler::edit_beta_key_distributed_flag_handler,
@@ -361,6 +363,9 @@ use crate::http_server::web_utils::response_success_helpers::*;
     ListAvailableWeightsSuccessResponse,
     ListBetaKeysError,
     ListBetaKeysQueryParams,
+    ListActiveUserSubscriptionsError,
+    ListActiveUserSubscriptionsResponse,
+    SubscriptionProductKey,
     ListBetaKeysSuccessResponse,
     ListCommentsError,
     ListCommentsPathInfo,