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
Add Cart API integration spec and OpenAPI documentation
Damian Legawiecd4a8b0318e92
diff --git a/api/spec/integration/spree/api/v3/store/cart_spec.rb b/api/spec/integration/spree/api/v3/store/cart_spec.rbnew file mode 100644index 0000000000..c1e7441ec4--- /dev/null+++ b/api/spec/integration/spree/api/v3/store/cart_spec.rb@@ -0,0 +1,168 @@+# frozen_string_literal: true++require 'swagger_helper'++RSpec.describe 'Cart API', type: :request, swagger_doc: 'api-reference/store.yaml' do+ include_context 'API v3 Store'++ path '/api/v3/store/cart' do+ get 'Get current cart' do+ tags 'Cart'+ produces 'application/json'+ security [api_key: [], bearer_auth: []]+ description <<~DESC+ Returns the current shopping cart (incomplete order).+ Authenticate via JWT token for logged-in users or via order_token parameter for guests.+ DESC++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: 'Authorization', in: :header, type: :string, required: false,+ description: 'Bearer JWT token for authenticated customers'+ parameter name: :order_token, in: :query, type: :string, required: false,+ description: 'Order token for guest checkout'++ response '200', 'cart found (guest)' do+ let(:cart) { create(:order_with_line_items, store: store) }+ let(:'x-spree-api-key') { api_key.token }+ let(:order_token) { cart.token }++ schema type: :object,+ allOf: [+ { '$ref' => '#/components/schemas/StoreOrder' },+ { type: :object, properties: { token: { type: :string } } }+ ]++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['number']).to eq(cart.number)+ expect(data['token']).to eq(cart.token)+ expect(data['line_items']).to be_present+ end+ end++ response '200', 'cart found (authenticated)' do+ let!(:cart) { create(:order_with_line_items, store: store, user: user) }+ let(:'x-spree-api-key') { api_key.token }+ let(:'Authorization') { "Bearer #{jwt_token}" }++ schema type: :object,+ allOf: [+ { '$ref' => '#/components/schemas/StoreOrder' },+ { type: :object, properties: { token: { type: :string } } }+ ]++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['number']).to eq(cart.number)+ end+ end++ response '404', 'no cart found' do+ let(:'x-spree-api-key') { api_key.token }++ schema '$ref' => '#/components/schemas/ErrorResponse'++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['error']['code']).to eq('record_not_found')+ end+ end+ end+ end++ path '/api/v3/store/cart/associate' do+ patch 'Associate guest cart with authenticated user' do+ tags 'Cart'+ produces 'application/json'+ security [api_key: [], bearer_auth: []]+ description <<~DESC+ Associates a guest cart with the currently authenticated user.+ Requires both JWT authentication and an order token.+ The order must not be completed and must not belong to another user.+ DESC++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: 'Authorization', in: :header, type: :string, required: true,+ description: 'Bearer JWT token (required)'+ parameter name: 'x-spree-order-token', in: :header, type: :string, required: false,+ description: 'Order token (can also be passed as query param)'+ parameter name: :order_token, in: :query, type: :string, required: false,+ description: 'Order token (alternative to header)'++ response '200', 'cart associated successfully' do+ let(:guest_cart) { create(:order_with_line_items, store: store, user: nil) }+ let(:'x-spree-api-key') { api_key.token }+ let(:'Authorization') { "Bearer #{jwt_token}" }+ let(:order_token) { guest_cart.token }++ schema type: :object,+ allOf: [+ { '$ref' => '#/components/schemas/StoreOrder' },+ { type: :object, properties: { token: { type: :string } } }+ ]++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['number']).to eq(guest_cart.number)+ expect(guest_cart.reload.user).to eq(user)+ end+ end++ response '401', 'unauthorized - JWT required' do+ let(:guest_cart) { create(:order_with_line_items, store: store, user: nil) }+ let(:'x-spree-api-key') { api_key.token }+ let(:'Authorization') { '' }+ let(:order_token) { guest_cart.token }++ schema '$ref' => '#/components/schemas/ErrorResponse'++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['error']['code']).to eq('authentication_required')+ end+ end++ response '403', 'cart belongs to another user' do+ let(:other_user) { create(:user) }+ let(:other_cart) { create(:order_with_line_items, store: store, user: other_user) }+ let(:'x-spree-api-key') { api_key.token }+ let(:'Authorization') { "Bearer #{jwt_token}" }+ let(:order_token) { other_cart.token }++ schema '$ref' => '#/components/schemas/ErrorResponse'++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['error']['code']).to eq('access_denied')+ end+ end++ response '404', 'cart not found' do+ let(:'x-spree-api-key') { api_key.token }+ let(:'Authorization') { "Bearer #{jwt_token}" }+ let(:order_token) { 'invalid_token' }++ schema '$ref' => '#/components/schemas/ErrorResponse'++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['error']['code']).to eq('record_not_found')+ end+ end++ response '422', 'cart already completed' do+ let(:completed_order) { create(:completed_order_with_totals, store: store, user: nil) }+ let(:'x-spree-api-key') { api_key.token }+ let(:'Authorization') { "Bearer #{jwt_token}" }+ let(:order_token) { completed_order.token }++ schema '$ref' => '#/components/schemas/ErrorResponse'++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['error']['code']).to eq('order_already_completed')+ end+ end+ end+ end+enddiff --git a/docs/api-reference/store.yaml b/docs/api-reference/store.yamlindex 9e19bad2d1..619371001b 100644--- a/docs/api-reference/store.yaml+++ b/docs/api-reference/store.yaml@@ -621,6 +621,126 @@ paths:type: stringpassword_confirmation:type: string+ "/api/v3/store/cart":+ get:+ summary: Get current cart+ tags:+ - Cart+ security:+ - api_key: []+ bearer_auth: []+ description: |+ Returns the current shopping cart (incomplete order).+ Authenticate via JWT token for logged-in users or via order_token parameter for guests.+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: false+ description: Bearer JWT token for authenticated customers+ schema:+ type: string+ - name: order_token+ in: query+ required: false+ description: Order token for guest checkout+ schema:+ type: string+ responses:+ '200':+ description: cart found+ content:+ application/json:+ schema:+ allOf:+ - "$ref": "#/components/schemas/StoreOrder"+ - type: object+ properties:+ token:+ type: string+ description: Order token for guest access+ '404':+ description: no cart found+ content:+ application/json:+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ "/api/v3/store/cart/associate":+ patch:+ summary: Associate guest cart with authenticated user+ tags:+ - Cart+ security:+ - api_key: []+ bearer_auth: []+ description: |+ Associates a guest cart with the currently authenticated user.+ Requires both JWT authentication and an order token.+ The order must not be completed and must not belong to another user.+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ description: Bearer JWT token (required)+ schema:+ type: string+ - name: x-spree-order-token+ in: header+ required: false+ description: Order token (can also be passed as query param)+ schema:+ type: string+ - name: order_token+ in: query+ required: false+ description: Order token (alternative to header)+ schema:+ type: string+ responses:+ '200':+ description: cart associated successfully+ content:+ application/json:+ schema:+ allOf:+ - "$ref": "#/components/schemas/StoreOrder"+ - type: object+ properties:+ token:+ type: string+ '401':+ description: unauthorized - JWT required+ content:+ application/json:+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ '403':+ description: cart belongs to another user+ content:+ application/json:+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ '404':+ description: cart not found+ content:+ application/json:+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ '422':+ description: cart already completed+ content:+ application/json:+ schema:+ "$ref": "#/components/schemas/ErrorResponse""/api/v3/store/orders/{order_id}/line_items":post:summary: Add item to cart@@ -2113,6 +2233,8 @@ tags:description: Individual categories- name: Countriesdescription: Available shipping countries+- name: Cart+ description: Current shopping cart management- name: Ordersdescription: Shopping cart and checkout- name: Line Items