Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Added more documentation to API v2 Base Controller methods
Damian Legawiecc9ddff1a0b76
diff --git a/api/app/controllers/spree/api/v2/base_controller.rb b/api/app/controllers/spree/api/v2/base_controller.rbindex 6b59062114..63fafe15c5 100644--- a/api/app/controllers/spree/api/v2/base_controller.rb+++ b/api/app/controllers/spree/api/v2/base_controller.rb@@ -20,6 +20,8 @@ module Spreerescue_from ArgumentError, with: :error_during_processingrescue_from ActionDispatch::Http::Parameters::ParseError, with: :error_during_processing+ # Returns the content type for the API+ # @return [String] The content type, eg 'application/vnd.api+json'def content_typeSpree::Api::Config[:api_v2_content_type]end@@ -42,18 +44,28 @@ module Spree).serializable_hashend+ # Returns a paginated collection+ # @return [Array] The paginated collectiondef paginated_collection@paginated_collection ||= collection_paginator.new(sorted_collection, params).callend+ # Returns the collection paginator+ # @return [Class] The collection paginator class, default is Spree::Shared::Paginatedef collection_paginatorSpree::Api::Dependencies.storefront_collection_paginator.constantizeend+ # Renders a serialized payload with the given status code+ # @param status [Integer] HTTP status code to return, eg 200, 201, 204+ # @yield [Hash] The serialized data to renderdef render_serialized_payload(status = 200)render json: yield, status: status, content_type: content_typeend+ # Renders a serialized error payload with the given status code+ # @param status [Integer] HTTP status code to return+ # @yield [Hash] The serialized data to renderdef render_error_payload(error, status = 422)json = if error.is_a?(ActiveModel::Errors){ error: error.full_messages.to_sentence, errors: error.messages }@@ -66,6 +78,9 @@ module Spreerender json: json, status: status, content_type: content_typeend+ # Renders a serialized result payload with the given status code+ # @param result [Object] The result to render+ # @param ok_status [Integer] HTTP status code to return if the result is successful, eg 200, 201, 204def render_result(result, ok_status = 200)if result.success?render_serialized_payload(ok_status) { serialize_resource(result.value) }@@ -74,6 +89,8 @@ module Spreeendend+ # Returns the current Spree user+ # @return [Spree.user_class] The current Spree userdef spree_current_userreturn nil unless doorkeeper_tokenreturn @spree_current_user if defined?(@spree_current_user)@@ -86,10 +103,17 @@ module Spreealias try_spree_current_user spree_current_user # for compatibility with spree_legacy_frontend+ # Authorizes the current Spree user for the given action and subject+ # @param action [Symbol] The action to authorize+ # @param subject [Object] The subject to authorize+ # @param args [Array] Additional arguments to pass to the authorize! method+ # @return [void]def spree_authorize!(action, subject, *args)authorize!(action, subject, *args)end+ # Raises an AccessDenied error if the current Spree user is nil+ # @raise [CanCan::AccessDenied] If the current Spree user is nildef require_spree_current_userraise CanCan::AccessDenied if spree_current_user.nil?end@@ -100,10 +124,13 @@ module Spreeend# this method can be extended in extensions or developer applications+ # @return [Hash] The ability optionsdef ability_options{ store: current_store }end+ # Returns the requested includes+ # @return [Array] The requested includesdef request_includes# if API user wants to receive only the bare-minimum# the API will return only the main resource without any included@@ -114,6 +141,8 @@ module Spreeendend+ # Returns the resource includes, useful to avoid N+1 queries+ # @return [Array] The resource includes, eg [:images, :variants]def resource_includes(request_includes || default_resource_includes).map(&:intern)end@@ -127,6 +156,8 @@ module Spree[]end+ # Returns the JSON API sparse fields+ # @return [Hash] The sparse fields, eg { product: [:name, :description] }def sparse_fieldsreturn unless params[:fields]&.respond_to?(:each)@@ -137,6 +168,9 @@ module Spreefields.presenceend+ # Returns the serializer global params+ # all of these params are passed down to the serializer+ # @return [Hash] The serializer paramsdef serializer_params{currency: current_currency,@@ -149,28 +183,43 @@ module Spree}end+ # Renders a 404 error payload+ # @param exception [Exception] The exception to render+ # @return [void]def record_not_found(exception)Rails.error.report(exception, context: { user_id: spree_current_user&.id }, source: 'spree.api')render_error_payload(I18n.t(:resource_not_found, scope: 'spree.api'), 404)end+ # Renders a 403 error payload+ # @param exception [Exception] The exception to render+ # @return [void]def access_denied(exception)Rails.error.report(exception, context: { user_id: spree_current_user&.id }, source: 'spree.api')render_error_payload(exception.message, 403)end+ # Renders a 401 error payload+ # @param exception [Exception] The exception to render+ # @return [void]def access_denied_401(exception)render_error_payload(exception.message, 401)end+ # Renders a 500 error payload when a payment gateway error occurs+ # @param exception [Exception] The exception to render+ # @return [void]def gateway_error(exception)Rails.error.report(exception, context: { user_id: spree_current_user&.id }, source: 'spree.api')render_error_payload(exception.message)end+ # Renders a 400 error payload when an error occurs during parameter parsing+ # @param exception [Exception] The exception to render+ # @return [void]def error_during_processing(exception)Rails.error.report(exception, context: { user_id: spree_current_user&.id }, source: 'spree.api')