Skip to content

armgit / spree

Public Imported from GitHub
0

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.

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.rb
index 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 Spree
rescue_from ArgumentError, with: :error_during_processing
rescue_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_type
Spree::Api::Config[:api_v2_content_type]
end
@@ -42,18 +44,28 @@ module Spree
).serializable_hash
end
+ # Returns a paginated collection
+ # @return [Array] The paginated collection
def paginated_collection
@paginated_collection ||= collection_paginator.new(sorted_collection, params).call
end
+ # Returns the collection paginator
+ # @return [Class] The collection paginator class, default is Spree::Shared::Paginate
def collection_paginator
Spree::Api::Dependencies.storefront_collection_paginator.constantize
end
+ # 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 render
def render_serialized_payload(status = 200)
render json: yield, status: status, content_type: content_type
end
+ # Renders a serialized error payload with the given status code
+ # @param status [Integer] HTTP status code to return
+ # @yield [Hash] The serialized data to render
def 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 Spree
render json: json, status: status, content_type: content_type
end
+ # 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, 204
def render_result(result, ok_status = 200)
if result.success?
render_serialized_payload(ok_status) { serialize_resource(result.value) }
@@ -74,6 +89,8 @@ module Spree
end
end
+ # Returns the current Spree user
+ # @return [Spree.user_class] The current Spree user
def spree_current_user
return nil unless doorkeeper_token
return @spree_current_user if defined?(@spree_current_user)
@@ -86,10 +103,17 @@ module Spree
alias 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 nil
def require_spree_current_user
raise CanCan::AccessDenied if spree_current_user.nil?
end
@@ -100,10 +124,13 @@ module Spree
end
# this method can be extended in extensions or developer applications
+ # @return [Hash] The ability options
def ability_options
{ store: current_store }
end
+ # Returns the requested includes
+ # @return [Array] The requested includes
def 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 Spree
end
end
+ # 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_fields
return unless params[:fields]&.respond_to?(:each)
@@ -137,6 +168,9 @@ module Spree
fields.presence
end
+ # Returns the serializer global params
+ # all of these params are passed down to the serializer
+ # @return [Hash] The serializer params
def 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')