spree_api 4.3.0 → 4.4.0.rc1

data/{app/models/spree → lib/spree/api}/api_dependencies.rb

@@ -20,13 +20,25 @@ module Spree
       :storefront_account_create_address_service, :storefront_account_update_address_service, :storefront_address_finder,
       :storefront_account_create_service, :storefront_account_update_service, :storefront_collection_sorter, :error_handler,
       :storefront_cart_empty_service, :storefront_cart_destroy_service, :storefront_credit_cards_destroy_service, :platform_products_sorter,
-      :storefront_cart_change_currency_service
+      :storefront_cart_change_currency_service, :storefront_payment_serializer,
+      :storefront_payment_create_service, :storefront_address_create_service, :storefront_address_update_service,
+      :storefront_checkout_select_shipping_method_service,
+
+      :platform_admin_user_serializer, :platform_coupon_handler, :platform_order_update_service,
+      :platform_order_use_store_credit_service, :platform_order_remove_store_credit_service,
+      :platform_order_complete_service, :platform_order_empty_service, :platform_order_destroy_service,
+      :platform_order_next_service, :platform_order_advance_service,
+      :platform_line_item_create_service, :platform_line_item_update_service, :platform_line_item_destroy_service,
+      :platform_order_approve_service, :platform_order_cancel_service,
+      :platform_shipment_change_state_service, :platform_shipment_create_service, :platform_shipment_update_service,
+      :platform_shipment_add_item_service, :platform_shipment_remove_item_service
     ].freeze
 
     attr_accessor *INJECTION_POINTS
 
     def initialize
       set_storefront_defaults
+      set_platform_defaults
     end
 
     private
@@ -58,16 +70,22 @@ module Spree
       @storefront_checkout_add_store_credit_service = Spree::Dependencies.checkout_add_store_credit_service
       @storefront_checkout_remove_store_credit_service = Spree::Dependencies.checkout_remove_store_credit_service
       @storefront_checkout_get_shipping_rates_service = Spree::Dependencies.checkout_get_shipping_rates_service
+      @storefront_checkout_select_shipping_method_service = Spree::Dependencies.checkout_select_shipping_method_service
 
       # account services
       @storefront_account_create_service = Spree::Dependencies.account_create_service
       @storefront_account_update_service = Spree::Dependencies.account_update_service
-      @storefront_account_create_address_service = Spree::Dependencies.account_create_address_service
-      @storefront_account_update_address_service = Spree::Dependencies.account_update_address_service
 
-      # credit cards
+      # address services
+      @storefront_address_create_service = Spree::Dependencies.address_create_service
+      @storefront_address_update_service = Spree::Dependencies.address_update_service
+
+      # credit card services
       @storefront_credit_cards_destroy_service = Spree::Dependencies.credit_cards_destroy_service
 
+      # payment services
+      @storefront_payment_create_service = Spree::Dependencies.payment_create_service
+
       # serializers
       @storefront_address_serializer = 'Spree::V2::Storefront::AddressSerializer'
       @storefront_cart_serializer = 'Spree::V2::Storefront::CartSerializer'
@@ -79,6 +97,7 @@ module Spree
       @storefront_shipment_serializer = 'Spree::V2::Storefront::ShipmentSerializer'
       @storefront_taxon_serializer = 'Spree::V2::Storefront::TaxonSerializer'
       @storefront_payment_method_serializer = 'Spree::V2::Storefront::PaymentMethodSerializer'
+      @storefront_payment_serializer = 'Spree::V2::Storefront::PaymentSerializer'
       @storefront_product_serializer = 'Spree::V2::Storefront::ProductSerializer'
       @storefront_estimated_shipment_serializer = 'Spree::V2::Storefront::EstimatedShippingRateSerializer'
       @storefront_store_serializer = 'Spree::V2::Storefront::StoreSerializer'
@@ -107,5 +126,38 @@ module Spree
 
       @error_handler = 'Spree::Api::ErrorHandler'
     end
+
+    def set_platform_defaults
+      # serializers
+      @platform_admin_user_serializer = 'Spree::Api::V2::Platform::UserSerializer'
+
+      # coupon code handler
+      @platform_coupon_handler = Spree::Dependencies.coupon_handler
+
+      # order services
+      @platform_order_recalculate_service = Spree::Dependencies.cart_recalculate_service
+      @platform_order_update_service = Spree::Dependencies.checkout_update_service
+      @platform_order_empty_service = Spree::Dependencies.cart_empty_service
+      @platform_order_destroy_service = Spree::Dependencies.cart_destroy_service
+      @platform_order_next_service = Spree::Dependencies.checkout_next_service
+      @platform_order_advance_service = Spree::Dependencies.checkout_advance_service
+      @platform_order_complete_service = Spree::Dependencies.checkout_complete_service
+      @platform_order_use_store_credit_service = Spree::Dependencies.checkout_add_store_credit_service
+      @platform_order_remove_store_credit_service = Spree::Dependencies.checkout_remove_store_credit_service
+      @platform_order_approve_service = Spree::Dependencies.order_approve_service
+      @platform_order_cancel_service = Spree::Dependencies.order_cancel_service
+
+      # line item services
+      @platform_line_item_create_service = Spree::Dependencies.line_item_create_service
+      @platform_line_item_update_service = Spree::Dependencies.line_item_update_service
+      @platform_line_item_destroy_service = Spree::Dependencies.line_item_destroy_service
+
+      # shipment services
+      @platform_shipment_create_service = Spree::Dependencies.shipment_create_service
+      @platform_shipment_update_service = Spree::Dependencies.shipment_update_service
+      @platform_shipment_change_state_service = Spree::Dependencies.shipment_change_state_service
+      @platform_shipment_add_item_service = Spree::Dependencies.shipment_add_item_service
+      @platform_shipment_remove_item_service = Spree::Dependencies.shipment_remove_item_service
+    end
   end
 end

data/lib/spree/api/engine.rb

@@ -17,13 +17,36 @@ module Spree
 
       initializer 'spree.api.checking_deprecated_preferences' do
         Spree::Api::Config.deprecated_preferences.each do |pref|
-          warn "[DEPRECATION] Spree::Api::Config[:#{pref[:name]}] is deprecated. #{pref[:message]}"
+          # FIXME: we should only notify about deprecated preferences that are in use, not all of them
+          # warn "[DEPRECATION] Spree::Api::Config[:#{pref[:name]}] is deprecated. #{pref[:message]}"
+        end
+      end
+
+      def self.activate
+        [
+          Spree::Address, Spree::Asset, Spree::CmsPage, Spree::CreditCard, Spree::CustomerReturn,
+          Spree::DigitalLink, Spree::Digital, Spree::InventoryUnit, Spree::LineItem, Spree::MenuItem,
+          Spree::Menu, Spree::OptionType, Spree::OptionValue, Spree::Order, Spree::PaymentCaptureEvent,
+          Spree::Payment, Spree::Price, Spree::Product, Spree::Promotion, Spree::Property, Spree::Prototype,
+          Spree::Refund, Spree::Reimbursement, Spree::ReturnAuthorization, Spree::ReturnItem, Spree::Role,
+          Spree::Shipment, Spree::ShippingCategory, Spree::ShippingMethod, Spree::ShippingRate,
+          Spree::StockItem, Spree::StockLocation, Spree::StockMovement, Spree::StockTransfer,
+          Spree::StoreCredit, Spree::Store, Spree::TaxCategory, Spree::TaxRate, Spree::Taxonomy,
+          Spree::Taxon, Spree::Variant, Spree::WishedItem, Spree::Wishlist, Spree::Zone
+        ].each do |webhookable_class|
+          webhookable_class.include(Spree::Webhooks::HasWebhooks)
+        end
+
+        Dir.glob(File.join(File.dirname(__FILE__), '../../../app/models/spree/api/webhooks/*_decorator*.rb')) do |c|
+          Rails.application.config.cache_classes ? require(c) : load(c)
         end
       end
 
       def self.root
         @root ||= Pathname.new(File.expand_path('../../..', __dir__))
       end
+
+      config.to_prepare &method(:activate).to_proc
     end
   end
 end

data/lib/spree/api/testing_support/factories/oauth_application_factory.rb

@@ -0,0 +1,6 @@
+FactoryBot.define do
+  factory :oauth_application, class: Spree::OauthApplication do
+    name { "Admin Panel" }
+    scopes { "admin" }
+  end
+end

data/lib/spree/api/testing_support/factories/webhook_event_factory.rb

@@ -0,0 +1,27 @@
+FactoryBot.define do
+  factory :webhook_event, aliases: [:event], class: Spree::Webhooks::Event do
+    subscriber
+
+    execution_time { rand(1..99_999) }
+    name { 'order.canceled' }
+    request_errors { '' }
+    sequence(:url) { |n| "https://www.url#{n}.com/" }
+
+    trait :failed do
+      response_code { '500' }
+      success { false }
+    end
+
+    trait :successful do
+      response_code { '200' }
+      success { true }
+    end
+
+    trait :blank do
+      execution_time { nil }
+      request_errors { nil }
+      subscriber_id { nil }
+      url { nil }
+    end
+  end
+end

data/lib/spree/api/testing_support/factories/webhook_subscriber_factory.rb

@@ -0,0 +1,13 @@
+FactoryBot.define do
+  factory :webhook_subscriber, aliases: [:subscriber], class: Spree::Webhooks::Subscriber do
+    sequence(:url) { |n| "https://www.url#{n}.com/" }
+
+    trait :active do
+      active { true }
+    end
+
+    trait :inactive do
+      active { false }
+    end
+  end
+end

data/lib/spree/api/testing_support/factories.rb

@@ -0,0 +1,3 @@
+Dir["#{File.dirname(__FILE__)}/factories/**"].each do |f|
+  load File.expand_path(f)
+end

data/lib/spree/api/testing_support/helpers.rb

@@ -25,7 +25,7 @@ module Spree
           allow(Spree.user_class).to receive(:find_by).with(hash_including(:spree_api_key)) { current_api_user }
         end
 
-        # This method can be overriden (with a let block) inside a context
+        # This method can be overridden (with a let block) inside a context
         # For instance, if you wanted to have an admin user instead.
         def current_api_user
           @current_api_user ||= stub_model(Spree.user_class, email: 'spree@example.com')

data/lib/spree/api/testing_support/jobs.rb

@@ -0,0 +1,18 @@
+RSpec.configure do |config|
+  # Force jobs to be executed in a synchronous way (see http://archive.today/xcb1E)
+  config.around do |example|
+    (ActiveJob::Base.descendants << ActiveJob::Base).each(&:disable_test_adapter)
+    ActiveJob::Base.queue_adapter = :inline
+    example.run
+    (ActiveJob::Base.descendants << ActiveJob::Base).each { |a| a.enable_test_adapter(ActiveJob::QueueAdapters::TestAdapter.new) }
+    ActiveJob::Base.queue_adapter = :test
+  end
+
+  config.before(:each, :job) do
+    ActiveJob::Base.queue_adapter = :test
+  end
+
+  config.after(:each, :job) do
+    ActiveJob::Base.queue_adapter = :inline
+  end
+end

data/lib/spree/api/testing_support/matchers/webhooks.rb

@@ -0,0 +1,67 @@
+# Passes if executing the code in the block there is a
+# `Spree::Webhooks::Subscribers::QueueRequests.call` method
+# call with the given `event` and `webhook_payload_body` arguments just once.
+#
+# @example
+#   expect { order.complete }.to emit_webhook_event('order.paid')
+#   expect do
+#     order.start_processing
+#     order.complete
+#   end.to emit_webhook_event('order.paid')
+#
+# It can also be negated, resulting in the expectation
+# waiting to not receive a `call` method call with the
+# given `event` and `webhook_payload_body` (`once` isn't taken into consideration).
+#
+# @example
+#   expect { order.complete }.not_to emit_webhook_event('order.paid')
+#   expect do
+#     order.start_processing
+#     order.complete
+#   end.not_to emit_webhook_event('order.paid')
+#
+# == Notes
+#
+# The matcher relies on a `webhook_payload_body` method previously defined which
+# isn't added to the matcher definition, because it acts in a different
+# way depending on what's the resource being tested.
+#
+RSpec::Matchers.define :emit_webhook_event do |event_to_emit|
+  match do |block|
+    queue_requests = instance_double(Spree::Webhooks::Subscribers::QueueRequests)
+
+    allow(Spree::Webhooks::Subscribers::QueueRequests).to receive(:new).and_return(queue_requests)
+    allow(queue_requests).to receive(:call).with(any_args)
+
+    with_webhooks_enabled { Timecop.freeze { block.call } }
+
+    expect(queue_requests).to(
+      have_received(:call).with(event_name: event_to_emit, webhook_payload_body: webhook_payload_body.to_json).once
+    )
+  end
+
+  def block_definition(obj_method)
+    # positive look-behinds must have a fixed length, using a straightforward match instead
+    obj_method.source.squish[/(expect *({|do) *)(.*?)( *(}|end).(not_)*to)/, 3]
+  end
+
+  failure_message do |obj_method|
+    block_def = block_definition(obj_method)
+    "Expected that executing `#{block_def}` emits the `#{event_to_emit}` Webhook event.\n" \
+      "Check that `#{block_def}` does implement `queue_webhooks_requests!` for " \
+      "`#{event_to_emit}` with the following webhook_payload_body: \n\n#{webhook_payload_body}."
+  end
+
+  failure_message_when_negated do |obj_method|
+    "Expected that executing `#{block_definition(obj_method)}` does not " \
+      "emit the `#{event_to_emit}` Webhook event with the following webhook_payload_body: #{webhook_payload_body}."
+  end
+
+  supports_block_expectations
+end
+
+def with_webhooks_enabled
+  ENV['DISABLE_SPREE_WEBHOOKS'] = nil
+  yield
+  ENV['DISABLE_SPREE_WEBHOOKS'] = 'true'
+end

data/lib/spree/api/testing_support/serializers.rb

@@ -0,0 +1,25 @@
+module Spree
+  class TestArgumentsJob < Spree::BaseJob
+    def perform(serializer); end
+  end
+end
+
+shared_examples 'an ActiveJob serializable hash' do
+  context 'Rails < 6', if: Rails::VERSION::MAJOR < 6 do
+    it 'can not be serialized by ActiveJob' do
+      expect { Spree::TestArgumentsJob.perform_later(subject) }.to(
+        raise_error(ActiveJob::SerializationError, 'Unsupported argument type: Symbol')
+      )
+    end
+  end
+
+  context 'Rails >= 6', if: Rails::VERSION::MAJOR >= 6 do
+    it 'can be serialized by ActiveJob' do
+      # It should fail if subject contains any custom instance (e.g Spree::Money)
+      expect { Spree::TestArgumentsJob.perform_later(subject) }.not_to raise_error
+      expect { Spree::TestArgumentsJob.perform_later(subject.merge(price: Spree::Money.new(0))) }.to(
+        raise_error(ActiveJob::SerializationError)
+      )
+    end
+  end
+end

data/lib/spree/api/testing_support/spree_webhooks.rb

@@ -0,0 +1,9 @@
+RSpec.configure do |config|
+  config.before(:each, :spree_webhooks) do
+    ENV['DISABLE_SPREE_WEBHOOKS'] = nil
+  end
+
+  config.after(:each, :spree_webhooks) do
+    ENV['DISABLE_SPREE_WEBHOOKS'] = 'true'
+  end
+end

data/lib/spree/api/testing_support/v2/base.rb

@@ -1,5 +1,5 @@
 shared_context 'API v2 tokens' do
-  let(:token) { Doorkeeper::AccessToken.create!(resource_owner_id: user.id, expires_in: nil) }
+  let(:token) { Spree::OauthAccessToken.create!(resource_owner: user, expires_in: nil) }
   let(:headers_bearer) { { 'Authorization' => "Bearer #{token.token}" } }
   let(:headers_order_token) { { 'X-Spree-Order-Token' => order.token } }
 end

data/lib/spree/api/testing_support/v2/current_order.rb

@@ -7,7 +7,40 @@ shared_context 'creates order with line item' do
   let!(:line_item) { create(:line_item, order: order, currency: currency) }
   let!(:headers)   { headers_bearer }
 
-  before { ensure_order_totals }
+  before do
+    order.reload
+    ensure_order_totals
+  end
+end
+
+shared_context 'order with a physical line item' do
+  include_context 'creates order with line item'
+end
+
+shared_context 'order with a digital line item' do
+  let!(:digital) { create(:digital) }
+  let!(:variant_digital) { digital.variant }
+  let!(:line_item) { create(:line_item, variant: variant_digital, order: order, currency: currency) }
+  let!(:headers) { headers_bearer }
+
+  before do
+    order.reload
+    ensure_order_totals
+  end
+end
+
+shared_context 'order with a physical and digital line item' do
+  let!(:digital) { create(:digital) }
+  let!(:variant_digital) { digital.variant }
+  let!(:digital_line_item) { create(:line_item, variant: variant_digital, order: order, currency: currency) }
+  let!(:physical_line_item) { create(:line_item, order: order, currency: currency) }
+
+  let!(:headers) { headers_bearer }
+
+  before do
+    order.reload
+    ensure_order_totals
+  end
 end
 
 shared_context 'creates guest order with guest token' do

data/lib/spree/api/testing_support/v2/platform_contexts.rb

@@ -1,36 +1,48 @@
 class String
   def articleize
-    %w(a e i o u).include?(self[0].downcase) ? "an #{self}" : "a #{self}"
+    if split.first == 'User'
+      "a #{self}"
+    else
+      %w(a e i o u).include?(self[0].downcase) ? "an #{self}" : "a #{self}"
+    end
   end
 end
 
 shared_context 'Platform API v2' do
   let(:store) { Spree::Store.default }
-  let(:admin_app) { Doorkeeper::Application.find_or_create_by!(name: 'Admin Panel', scopes: 'admin', redirect_uri: '') }
-  let(:read_app) { Doorkeeper::Application.find_or_create_by!(name: 'Read App', scopes: 'read', redirect_uri: '') }
+  let(:admin_app) { Spree::OauthApplication.find_or_create_by!(name: 'Admin Panel', scopes: 'admin', redirect_uri: '') }
+  let(:read_app) { Spree::OauthApplication.find_or_create_by!(name: 'Read App', scopes: 'read', redirect_uri: '') }
   let(:oauth_token) do
-    Doorkeeper::AccessToken.create!(
+    Spree::OauthAccessToken.create!(
       application_id: admin_app.id,
       scopes: admin_app.scopes
     )
   end
   let(:read_oauth_token) do
-    Doorkeeper::AccessToken.create!(
+    Spree::OauthAccessToken.create!(
       application_id: read_app.id,
       scopes: read_app.scopes
     )
   end
   let(:user_oauth_token) do
-    Doorkeeper::AccessToken.create!(
-      resource_owner_id: user.id,
+    Spree::OauthAccessToken.create!(
+      resource_owner: user,
       application_id: admin_app.id,
       scopes: admin_app.scopes
     )
   end
+  let(:user_oauth_token_without_app) do
+    Spree::OauthAccessToken.create!(
+      resource_owner: user,
+      scopes: 'admin'
+    )
+  end
+
 
   let(:valid_authorization) { "Bearer #{oauth_token.token}" }
   let(:valid_read_authorization) { "Bearer #{read_oauth_token.token}" }
   let(:valid_user_authorization) { "Bearer #{user_oauth_token.token}" }
+  let(:valid_user_authorization_without_app) { "Bearer #{user_oauth_token_without_app.token}" }
   let(:bogus_authorization) { "Bearer #{::Base64.strict_encode64('bogus:bogus')}" }
 
   let(:Authorization) { valid_authorization }
@@ -53,9 +65,14 @@ def json_api_include_parameter(example = '')
   parameter name: :include, in: :query, type: :string, description: JSON_API_INCLUDES_DESCRIPTION, example: example
 end
 
-def json_api_filter_parameter(example = '')
-  let(:filter) { nil }
-  parameter name: :filter, in: :query, type: :string, description: JSON_API_FILTER_DESCRIPTION, example: example
+def json_api_filter_parameter(examples = [])
+  examples.each do |api_filter|
+    name = api_filter[:name].to_sym
+    example = api_filter[:example]
+    let(name) { nil }
+
+    parameter name: name, in: :query, type: :string, description: JSON_API_FILTER_DESCRIPTION, example: example
+  end
 end
 
 shared_examples 'authentication failed' do
@@ -95,21 +112,21 @@ shared_examples 'records returned' do
 end
 
 shared_examples 'record created' do
-  response '201', 'record created' do
+  response '201', 'Record created' do
     schema '$ref' => '#/components/schemas/resource'
     run_test!
   end
 end
 
 shared_examples 'record updated' do
-  response '200', 'record updated' do
+  response '200', 'Record updated' do
     schema '$ref' => '#/components/schemas/resource'
     run_test!
   end
 end
 
 shared_examples 'invalid request' do |param_name|
-  response '422', 'invalid request' do
+  response '422', 'Invalid request' do
     let(param_name) { invalid_param_value }
     schema '$ref' => '#/components/schemas/validation_errors'
     run_test!
@@ -117,15 +134,17 @@ shared_examples 'invalid request' do |param_name|
 end
 
 # index action
-shared_examples 'GET records list' do |resource_name, include_example, filter_example|
-  get "Returns a list of #{resource_name.pluralize}" do
-    tags resource_name.pluralize
+shared_examples 'GET records list' do |resource_name, **options|
+  endpoint_name = options[:custom_endpoint_name] || resource_name
+
+  get "Return a list of #{endpoint_name.pluralize}" do
+    tags endpoint_name.pluralize
     security [ bearer_auth: [] ]
-    description "Returns a list of #{resource_name.pluralize}"
+    description "Returns a list of #{endpoint_name.pluralize}"
     operationId "#{resource_name.parameterize.pluralize.to_sym}-list"
     include_context 'jsonapi pagination'
-    json_api_include_parameter(include_example)
-    json_api_filter_parameter(filter_example)
+    json_api_include_parameter(options[:include_example]) unless options[:include_example].nil?
+    json_api_filter_parameter(options[:filter_examples]) unless options[:filter_examples].nil?
 
     before { records_list }
 
@@ -135,14 +154,16 @@ shared_examples 'GET records list' do |resource_name, include_example, filter_ex
 end
 
 # show
-shared_examples 'GET record' do |resource_name, include_example|
-  get "Returns #{resource_name.articleize}" do
-    tags resource_name.pluralize
+shared_examples 'GET record' do |resource_name, **options|
+  endpoint_name = options[:custom_endpoint_name] || resource_name
+
+  get "Return #{endpoint_name.articleize}" do
+    tags endpoint_name.pluralize
     security [ bearer_auth: [] ]
-    description "Returns #{resource_name.articleize}"
+    description "Returns #{endpoint_name.articleize}"
     operationId "show-#{resource_name.parameterize.to_sym}"
     parameter name: :id, in: :path, type: :string
-    json_api_include_parameter(include_example)
+    json_api_include_parameter(options[:include_example]) unless options[:include_example].nil?
 
     it_behaves_like 'record found'
     it_behaves_like 'record not found'
@@ -151,54 +172,82 @@ shared_examples 'GET record' do |resource_name, include_example|
 end
 
 # create
-shared_examples 'POST create record' do |resource_name, include_example|
+shared_examples 'POST create record' do |resource_name, **options|
+  custom_create_params = options[:custom_create_params] || nil
+  endpoint_name = options[:custom_endpoint_name] || resource_name
   param_name = resource_name.parameterize(separator: '_').to_sym
-
-  post "Creates #{resource_name.articleize}" do
-    tags resource_name.pluralize
-    consumes 'application/json'
+  consumes_kind = options[:consumes_kind] || 'application/json'
+  request_data_type = case consumes_kind
+                      when 'multipart/form-data'
+                        :formData
+                      else
+                        :body
+                      end
+
+  post "Create #{endpoint_name.articleize}" do
+    tags endpoint_name.pluralize
+    consumes consumes_kind
     security [ bearer_auth: [] ]
-    description "Creates #{resource_name.articleize}"
+    description "Creates #{endpoint_name.articleize}"
     operationId "create-#{resource_name.parameterize.to_sym}"
-    parameter name: param_name, in: :body, schema: { '$ref' => "#/components/schemas/#{param_name}_params" }
-    json_api_include_parameter(include_example)
+    if custom_create_params
+      parameter name: param_name, in: request_data_type, schema: custom_create_params
+    else
+      parameter name: param_name, in: request_data_type, schema: { '$ref' => "#/components/schemas/create_#{param_name}_params" }
+    end
+    json_api_include_parameter(options[:include_example]) unless options[:include_example].nil?
 
     let(param_name) { valid_create_param_value }
 
     it_behaves_like 'record created'
-    it_behaves_like 'invalid request', param_name
+    it_behaves_like 'invalid request', param_name unless options[:skip_invalid_params] == true
   end
 end
 
 # update
-shared_examples 'PUT update record' do |resource_name, include_example|
+shared_examples 'PATCH update record' do |resource_name, **options|
+  custom_update_params = options[:custom_update_params] || nil
+  endpoint_name = options[:custom_endpoint_name] || resource_name
   param_name = resource_name.parameterize(separator: '_').to_sym
-
-  put "Updates #{resource_name.articleize}" do
-    tags resource_name.pluralize
+  consumes_kind = options[:consumes_kind] || 'application/json'
+  request_data_type = case consumes_kind
+                      when 'multipart/form-data'
+                        :formData
+                      else
+                        :body
+                      end
+
+  patch "Update #{endpoint_name.articleize}" do
+    tags endpoint_name.pluralize
     security [ bearer_auth: [] ]
-    description "Updates #{resource_name.articleize}"
+    description "Updates #{endpoint_name.articleize}"
     operationId "update-#{resource_name.parameterize.to_sym}"
-    consumes 'application/json'
+    consumes consumes_kind
     parameter name: :id, in: :path, type: :string
-    parameter name: param_name, in: :body, schema: { '$ref' => "#/components/schemas/#{param_name}_params" }
-    json_api_include_parameter(include_example)
+    if custom_update_params
+      parameter name: param_name, in: request_data_type, schema: custom_update_params
+    else
+      parameter name: param_name, in: request_data_type, schema: { '$ref' => "#/components/schemas/update_#{param_name}_params" }
+    end
+    json_api_include_parameter(options[:include_example]) unless options[:include_example].nil?
 
     let(param_name) { valid_update_param_value }
 
     it_behaves_like 'record updated'
-    it_behaves_like 'invalid request', param_name
+    it_behaves_like 'invalid request', param_name unless options[:skip_invalid_params] == true
     it_behaves_like 'record not found'
     it_behaves_like 'authentication failed'
   end
 end
 
 # destroy
-shared_examples 'DELETE record' do |resource_name|
-  delete "Deletes #{resource_name.articleize}" do
-    tags resource_name.pluralize
+shared_examples 'DELETE record' do |resource_name, **options|
+  endpoint_name = options[:custom_endpoint_name] || resource_name
+
+  delete "Delete #{endpoint_name.articleize}" do
+    tags endpoint_name.pluralize
     security [ bearer_auth: [] ]
-    description "Deletes #{resource_name.articleize}"
+    description "Deletes #{endpoint_name.articleize}"
     operationId "delete-#{resource_name.parameterize.to_sym}"
     parameter name: :id, in: :path, type: :string
 
@@ -208,17 +257,17 @@ shared_examples 'DELETE record' do |resource_name|
   end
 end
 
-shared_examples 'CRUD examples' do |resource_name, include_example, filter_example|
+shared_examples 'CRUD examples' do |resource_name, **options|
   resource_path = resource_name.parameterize(separator: '_').pluralize
 
   path "/api/v2/platform/#{resource_path}" do
-    include_examples 'GET records list', resource_name, include_example, filter_example
-    include_examples 'POST create record', resource_name, include_example
+    include_examples 'GET records list', resource_name, options
+    include_examples 'POST create record', resource_name, options
   end
 
   path "/api/v2/platform/#{resource_path}/{id}" do
-    include_examples 'GET record', resource_name, include_example
-    include_examples 'PUT update record', resource_name, include_example
-    include_examples 'DELETE record', resource_name
+    include_examples 'GET record', resource_name, options
+    include_examples 'PATCH update record', resource_name, options
+    include_examples 'DELETE record', resource_name, options
   end
 end