Deprecate duplicated variant routes

As in #4385:

- We keep shallow member routes. We deprecate nested member routes.
- We keep creation nested route. We deprecate creation shallow route.
- We keep both shallow and nested collection routes (more flexibility
for storefronts).

api/app/controllers/spree/api/variants_controller.rb

@@ -6,6 +6,12 @@ class VariantsController < Spree::Api::BaseController
       before_action :product
 
       def create
+        Spree::Deprecation.warn <<~MSG unless request.path.include?('/products/')
+          This route is deprecated. Use the route nested within the product resource:
+
+            POST api/products/{product_id}/variants
+        MSG
+
         authorize! :create, Variant
         @variant = scope.new(variant_params)
         if @variant.save
@@ -16,6 +22,8 @@ def create
       end
 
       def destroy
+        warn_if_nested_member_route
+
         @variant = scope.accessible_by(current_ability, :destroy).find(params[:id])
         @variant.discard
         respond_with(@variant, status: 204)
@@ -42,12 +50,16 @@ def new
       end
 
       def show
+        warn_if_nested_member_route
+
         @variant = scope.includes(include_list)
           .find(params[:id])
         respond_with(@variant)
       end
 
       def update
+        warn_if_nested_member_route
+
         @variant = scope.accessible_by(current_ability, :update).find(params[:id])
         if @variant.update(variant_params)
           respond_with(@variant, status: 200, default_template: :show)
@@ -58,6 +70,14 @@ def update
 
       private
 
+      def warn_if_nested_member_route
+        Spree::Deprecation.warn <<~MSG if request.path.include?('/products/')
+          This route is deprecated. Use shallow version instead:
+
+            #{request.method.upcase} api/variants/:id
+        MSG
+      end
+
       def product
         @product ||= Spree::Product.accessible_by(current_ability, :show).friendly.find(params[:product_id]) if params[:product_id]
       end

api/config/routes.rb

@@ -12,10 +12,16 @@
 
     resources :products do
       resources :images
+      # TODO: Use shallow option on Solidus v4.0
       resources :variants
       resources :product_properties
     end
 
+    # TODO: Use only: :index on Solidus v4.0
+    resources :variants do
+      resources :images
+    end
+
     concern :order_routes do
       resources :line_items
       resources :payments do
@@ -47,10 +53,6 @@
       end
     end
 
-    resources :variants do
-      resources :images
-    end
-
     resources :option_types do
       # TODO: Use shallow option on Solidus v4.0
       resources :option_values

api/openapi/solidus-api.oas.yml

@@ -682,7 +682,10 @@ paths:
         '404':
           $ref: '#/components/responses/not-found'
       summary: Get product variant
-      description: Retrieves a product's variant.
+      description: |-
+        **DEPRECATED**: Use *GET /variants/{id}* instead
+
+        Retrieves a product's variant.
       operationId: get-product-variant
       tags:
         - Variants
@@ -714,7 +717,10 @@ paths:
         '422':
           $ref: '#/components/responses/delete-restriction'
       summary: Delete product variant
-      description: Deletes a product's variant.
+      description: |-
+        **DEPRECATED**: Use *DELETE /variants/{id}* instead
+
+        Deletes a product's variant.
       operationId: delete-product-variant
       tags:
         - Variants
@@ -735,7 +741,10 @@ paths:
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Update product variant
-      description: Updates a product's variant.
+      description: |-
+        **DEPRECATED**: Use *PUT /variants/{id}* instead
+
+        Updates a product's variant.
       operationId: update-product-variant
       tags:
         - Variants
@@ -857,7 +866,10 @@ paths:
         '422':
           $ref: '#/components/responses/unprocessable-entity'
       summary: Create variant
-      description: 'Creates a variant. Only users with `can :create, Variant` permissions can perform this action.'
+      description: |-
+        **DEPRECATED**: Use *POST /products/{product_id}/variants* instead
+
+        Creates a variant. Only users with `can :create, Variant` permissions can perform this action.
       operationId: create-variant
       tags:
         - Variants

api/spec/requests/spree/api/variants_spec.rb

@@ -216,6 +216,14 @@ module Spree::Api
                                                         :option_type_id])
       end
 
+      it "deprecates showing a variant through a nested route" do
+        expect(Spree::Deprecation).to receive(:warn).with(%r[deprecated.*GET api/variants]m)
+
+        get spree.api_product_variant_path(product, variant)
+
+        expect(json_response).to have_attributes(show_attributes)
+      end
+
       it "can see a single variant with images" do
         variant.images.create!(attachment: image("blank.jpg"))
 
@@ -276,7 +284,7 @@ module Spree::Api
     end
 
     it "cannot create a new variant if not an admin" do
-      post spree.api_variants_path, params: { variant: { sku: "12345" } }
+      post spree.api_product_variants_path(product), params: { variant: { sku: "12345" } }
       assert_unauthorized!
     end
 
@@ -315,6 +323,13 @@ module Spree::Api
         expect(variant.product.variants.count).to eq(1)
       end
 
+      it "deprecates creating a variant through a shallow route" do
+        expect(Spree::Deprecation).to receive(:warn).with(%r[deprecated.*api/products/{product_id}/variants]m)
+
+        post spree.api_variants_path, params: { variant: { sku: "12345", "product_id": product.id } }
+        expect(json_response).to have_attributes(new_attributes)
+      end
+
       it "creates new variants with nested option values" do
         option_values = create_list(:option_value, 2)
         expect do
@@ -346,12 +361,28 @@ module Spree::Api
         expect(response.status).to eq(200)
       end
 
+      it "deprecates updating a variant through a nested route" do
+        expect(Spree::Deprecation).to receive(:warn).with(%r[deprecated.*PUT api/variants]m)
+
+        put spree.api_product_variant_path(product, variant), params: { variant: { sku: "12345" } }
+
+        expect(json_response).to have_attributes(show_attributes)
+      end
+
       it "can delete a variant" do
         delete spree.api_variant_path(variant)
         expect(response.status).to eq(204)
         expect { Spree::Variant.find(variant.id) }.to raise_error(ActiveRecord::RecordNotFound)
       end
 
+      it "deprecates updating a variant through a nested route" do
+        expect(Spree::Deprecation).to receive(:warn).with(%r[deprecated.*DELETE api/variants]m)
+
+        delete spree.api_product_variant_path(product, variant)
+
+        expect { Spree::Variant.find(variant.id) }.to raise_error(ActiveRecord::RecordNotFound)
+      end
+
       it 'variants returned contain cost price data' do
         get spree.api_variants_path
         expect(json_response["variants"].first.key?(:cost_price)).to eq true