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 `spree:api_resource` generator for v3-conformant API resources
Damian Legawiec56bf026a92c1
diff --git a/scripts/docker-compose.edge.yml b/scripts/docker-compose.edge.ymlindex e37b204924..f4f83e6102 100644--- a/scripts/docker-compose.edge.yml+++ b/scripts/docker-compose.edge.yml@@ -26,7 +26,7 @@ services:environment:SPREE_PATH: ${SPREE_PATH}volumes:- - ${SPREE_PATH}:${SPREE_PATH}:ro+ - ${SPREE_PATH}:${SPREE_PATH}# Hard-bypass the starter's bin/docker-entrypoint, which auto-runs# `db:prepare` when the command is `bin/rails server`. The dev compose# claims to bypass it but doesn't actually set entrypoint: [], so we@@ -37,5 +37,5 @@ services:environment:SPREE_PATH: ${SPREE_PATH}volumes:- - ${SPREE_PATH}:${SPREE_PATH}:ro+ - ${SPREE_PATH}:${SPREE_PATH}entrypoint: []diff --git a/spree/core/lib/generators/spree/api_resource/api_resource_generator.rb b/spree/core/lib/generators/spree/api_resource/api_resource_generator.rbnew file mode 100644index 0000000000..ddb029a5ec--- /dev/null+++ b/spree/core/lib/generators/spree/api_resource/api_resource_generator.rb@@ -0,0 +1,341 @@+# frozen_string_literal: true++require_relative '../model/model_generator'++module Spree+ # spree:api_resource — scaffold a complete v3-conformant API resource on+ # top of `spree:model`.+ #+ # bin/rails g spree:api_resource Brand name:string:uniq active:boolean --writable+ #+ # Inherits from Spree::ModelGenerator (model + migration with Spree+ # conventions: prefixed IDs, spree_-prefixed tables, null: false, optional+ # acts_as_paranoid + Spree::Metafields). Adds on top:+ #+ # - Store + Admin controllers (managed — overwrite on re-run)+ # - Store + Admin serializers (managed — overwrite on re-run)+ # - Factory (managed — overwrite on re-run)+ # - Controller specs (managed — overwrite on re-run)+ # - Routes (idempotent inject between sentinels)+ #+ # Owned-once contract: if the model file already exists, the generator+ # leaves it (and the migration) alone — domain code is yours after+ # creation. Re-running adds/updates API surfaces only.+ #+ # TypeScript types and Zod schemas regenerate automatically via the+ # Lefthook pre-commit hook when a serializer file is staged.+ #+ # See docs/plans/spree-dev-cli-and-generators.md (Track 3) for the+ # owned-once / managed-forever / append-only contract.+ class ApiResourceGenerator < Spree::ModelGenerator+ # API-specific templates live alongside this generator. Parent's+ # templates (model.rb.tt, create_table_migration.rb.tt) are inherited+ # via Spree::ModelGenerator.source_paths.+ def self.source_paths+ [File.expand_path('templates', __dir__), *superclass.source_paths]+ end++ class_option :store,+ type: :boolean,+ default: true,+ desc: 'Generate Store API controller + serializer'++ class_option :admin,+ type: :boolean,+ default: true,+ desc: 'Generate Admin API controller + serializer'++ class_option :store_name,+ type: :string,+ desc: 'Expose Store API under a different name (e.g. Brand → Discount)'++ class_option :writable,+ type: :boolean,+ default: false,+ desc: 'Make the Store API writable (create/update/destroy)'++ class_option :skip_routes,+ type: :boolean,+ default: false,+ desc: "Don't inject routes into spree/api/config/routes.rb"++ class_option :skip_specs,+ type: :boolean,+ default: false,+ desc: "Don't generate controller specs"++ # api_resource generates its own controller specs and factory directly,+ # so we remove the parent's spec/fixture hooks. Otherwise Rails would+ # invoke rspec (boots Rails → PendingMigrationError on the freshly-+ # created migration; or "[not found]" warning on re-runs).+ remove_hook_for :test_framework+ remove_hook_for :fixture_replacement if hooks[:fixture_replacement]++ # Re-runs are part of the contract (owned-once gating skips the model+ # and migration). Rails' NamedBase collision check would otherwise abort+ # the second run with "Spree::Brand is already used in your application".+ class_option :skip_collision_check, type: :boolean, default: true, desc: false++ desc 'Scaffold a complete v3-conformant API resource (model + migration + controllers + serializers + routes + factory + specs)'++ # --- Owned-once gating ---+ #+ # Thor's parent commands run BEFORE subclass commands (commands merge+ # from superclass first). So we can't snapshot model existence in a+ # subclass action and have parent's create_model_file see it. We+ # capture state in initialize, before any action runs.++ def initialize(*args)+ super+ @model_existed_before_run = File.exist?(model_file_destination)+ end++ # Override parent: skip if the model file already exists. Re-running+ # never overwrites domain code.+ def create_model_file+ if @model_existed_before_run+ say_status :skip, "model #{model_file_destination} (owned-once; already exists)", :yellow+ return+ end+ super+ end++ # Override parent: skip if the model existed before this run. Migrations+ # are append-only — schema changes get a separate migration:+ # pnpm exec spree rails g migration AddFooToBar foo:string+ def create_migration_file+ if @model_existed_before_run+ say_status :skip, 'migration (model already exists; add a new migration for schema changes)', :yellow+ return+ end+ super+ end++ # --- API surface ---++ def create_store_controller+ return unless options[:store]++ template 'store_controller.rb.tt', store_controller_path+ end++ def create_admin_controller+ return unless options[:admin]++ template 'admin_controller.rb.tt', admin_controller_path+ end++ def create_store_serializer+ return unless options[:store]++ template 'store_serializer.rb.tt', store_serializer_path++ # --store-name aliases the store-facing class under a different name+ # (e.g. Brand → Discount) while keeping the model/table internal.+ if store_external_name != bare_class_name+ template 'store_aliased_serializer.rb.tt',+ "app/serializers/spree/api/v3/#{store_external_name.underscore}_serializer.rb"+ end+ end++ def create_admin_serializer+ return unless options[:admin]++ template 'admin_serializer.rb.tt', admin_serializer_path+ end++ def create_factory+ template 'factory.rb.tt', "lib/spree/testing_support/factories/#{singular_name}_factory.rb"+ end++ def create_controller_specs+ return if options[:skip_specs]++ if options[:store]+ template 'store_controller_spec.rb.tt',+ "spec/controllers/spree/api/v3/store/#{plural_name}_controller_spec.rb"+ end+ if options[:admin]+ template 'admin_controller_spec.rb.tt',+ "spec/controllers/spree/api/v3/admin/#{plural_name}_controller_spec.rb"+ end+ end++ def inject_routes+ return if options[:skip_routes]++ routes_file = api_routes_path++ unless File.exist?(routes_file) && File.writable?(routes_file)+ say_status :skip, "routes.rb at #{routes_file} (not writable — only edge installs can modify gem source)", :yellow+ return+ end++ inject_route_for(:store, store_route_line) if options[:store]+ inject_route_for(:admin, admin_route_line) if options[:admin]+ end++ def print_summary+ say ''+ say "✓ Generated Spree::#{bare_class_name} API resource", :green+ say ''+ say " Prefixed ID: #{id_prefix}_xxxxxxxxxx (edit `has_prefix_id` in the model to change)"+ if store_external_name != bare_class_name+ say " Store API: /api/v3/store/#{store_external_plural} (aliased from #{bare_class_name})"+ elsif options[:store]+ say " Store API: /api/v3/store/#{plural_name} (#{writable? ? 'full CRUD' : 'read-only'})"+ end+ say " Admin API: /api/v3/admin/#{plural_name} (full CRUD)" if options[:admin]+ say ''+ say ' Next steps:', :yellow+ say ' 1. Review the generated model — add validations, scopes, callbacks'+ say ' 2. Apply the migration: pnpm exec spree migrate'+ say ' 3. Set up authorization (CanCanCan ability) for the resource'+ say ' 4. Decide whether this resource is store-scoped (add `has_many` on Store)'+ if options[:store] || options[:admin]+ say ' 5. Run the specs: pnpm exec spree exec bundle exec rspec spec/controllers/spree/api/v3/'+ end+ say ''+ end++ # --- Helpers exposed to templates and other actions ---++ no_tasks do+ def writable?+ options[:writable]+ end++ # NamedBase's class_name includes the namespace prefix (e.g. Spree::Brand+ # when class_path is forced to ["spree"]). Templates that nest under+ # `module Spree` need the bare name to avoid Spree::Spree::Brand.+ def bare_class_name+ class_name.demodulize+ end++ # The external name the Store API surfaces this as. Defaults to the+ # canonical class name; --store-name overrides (e.g. Brand → Discount).+ def store_external_name+ options[:store_name] || bare_class_name+ end++ def store_external_plural+ store_external_name.tableize+ end++ # Used in templates that refer to the resource by singular/plural+ # snake_case identifiers (factory names, file names, route names).+ def singular_name+ file_name+ end++ def plural_name+ file_name.pluralize+ end++ # Attributes the controller permits on write. By default, every column+ # except references (FKs come through nested), attachments, rich text.+ def permitted_attribute_names+ attributes+ .reject { |a| a.reference? || a.attachment? || a.attachments? || a.rich_text? || a.token? || a.password_digest? }+ .map(&:name)+ end+ end++ private++ # Where the model file lands. We use parent's class_path + file_name so+ # this stays in sync with whatever Spree::ModelGenerator decides.+ def model_file_destination+ File.join('app/models', class_path, "#{file_name}.rb")+ end++ def store_controller_path+ "app/controllers/spree/api/v3/store/#{plural_name}_controller.rb"+ end++ def admin_controller_path+ "app/controllers/spree/api/v3/admin/#{plural_name}_controller.rb"+ end++ def store_serializer_path+ "app/serializers/spree/api/v3/#{singular_name}_serializer.rb"+ end++ def admin_serializer_path+ "app/serializers/spree/api/v3/admin/#{singular_name}_serializer.rb"+ end++ # Absolute path to spree_api's routes.rb. On edge installs (SPREE_PATH set)+ # this resolves to the monorepo source; on a published-gem install it+ # resolves to the gem cache directory (typically read-only).+ def api_routes_path+ File.join(Gem.loaded_specs['spree_api'].full_gem_path, 'config/routes.rb')+ end++ # The routes line we inject into the Store namespace.+ # --writable expands to full CRUD; default is read-only (index/show).+ def store_route_line+ if store_external_name != bare_class_name+ # --store-name Discount: alias under a different external name,+ # but route to the canonical controller (brands).+ if writable?+ " resources :#{store_external_plural}, controller: '#{plural_name}'"+ else+ " resources :#{store_external_plural}, controller: '#{plural_name}', only: [:index, :show]"+ end+ elsif writable?+ " resources :#{plural_name}"+ else+ " resources :#{plural_name}, only: [:index, :show]"+ end+ end++ # Admin always gets full CRUD.+ def admin_route_line+ " resources :#{plural_name}"+ end++ # The 8-space-indented sentinel markers.+ BEGIN_MARKER = ' # BEGIN spree:api_resource managed routes'.freeze+ END_MARKER = ' # END spree:api_resource managed routes'.freeze++ # Idempotent injection. First run: insert sentinels + the route line at+ # the top of the namespace. Subsequent runs: find the existing sentinels+ # and insert the route line between them only if not already present.+ def inject_route_for(namespace, route_line)+ file = api_routes_path+ content = File.read(file)++ sentinel_pattern = sentinel_pattern_for(namespace)++ if content =~ sentinel_pattern+ # Sentinels exist for this namespace — find the block, check if+ # `resources :<plural>` is already there.+ block = Regexp.last_match(0)+ if block.include?(route_line.strip)+ say_status :identical, "routes.rb (#{namespace}: #{route_line.strip})", :blue+ return+ end++ # Insert just above the END marker, preserving the existing block.+ new_block = block.sub(END_MARKER, "#{route_line}\n#{END_MARKER}")+ File.write(file, content.sub(block, new_block))+ say_status :inject, "routes.rb (#{namespace}: #{route_line.strip})", :green+ else+ # First run for this namespace — inject the full block right after+ # the namespace's opening line.+ opening = " namespace :#{namespace} do\n"+ new_block = "#{BEGIN_MARKER}\n#{route_line}\n#{END_MARKER}\n\n"+ File.write(file, content.sub(opening, opening + new_block))+ say_status :inject, "routes.rb (#{namespace}: sentinels + #{route_line.strip})", :green+ end+ end++ # Match the BEGIN…END block scoped to a specific namespace. Anchors on+ # the namespace's opening line so we don't accidentally match the Admin+ # block when looking at Store and vice versa.+ def sentinel_pattern_for(namespace)+ /#{Regexp.escape("namespace :#{namespace} do")}.*?#{Regexp.escape(BEGIN_MARKER)}.*?#{Regexp.escape(END_MARKER)}/m+ end+ end+enddiff --git a/spree/core/lib/generators/spree/api_resource/templates/admin_controller.rb.tt b/spree/core/lib/generators/spree/api_resource/templates/admin_controller.rb.ttnew file mode 100644index 0000000000..ab270dc789--- /dev/null+++ b/spree/core/lib/generators/spree/api_resource/templates/admin_controller.rb.tt@@ -0,0 +1,23 @@+module Spree+ module Api+ module V3+ module Admin+ class <%= plural_name.camelize %>Controller < ResourceController+ protected++ def model_class+ Spree::<%= class_name.demodulize %>+ end++ def serializer_class+ Spree.api.admin_<%= singular_name %>_serializer+ end++ def permitted_params+ params.permit(<%= permitted_attribute_names.map { |a| ":#{a}" }.join(', ') %>)+ end+ end+ end+ end+ end+enddiff --git a/spree/core/lib/generators/spree/api_resource/templates/admin_controller_spec.rb.tt b/spree/core/lib/generators/spree/api_resource/templates/admin_controller_spec.rb.ttnew file mode 100644index 0000000000..97ade16b40--- /dev/null+++ b/spree/core/lib/generators/spree/api_resource/templates/admin_controller_spec.rb.tt@@ -0,0 +1,59 @@+require 'spec_helper'++RSpec.describe Spree::Api::V3::Admin::<%= plural_name.camelize %>Controller, type: :controller do+ render_views++ include_context 'API v3 Admin authenticated'++ let!(:<%= singular_name %>) { create(:<%= singular_name %>) }++ before { request.headers.merge!(headers) }++ describe 'GET #index' do+ subject { get :index, as: :json }++ it 'returns <%= plural_name %>' do+ subject+ expect(response).to have_http_status(:ok)+ expect(json_response['data']).to be_an(Array)+ expect(json_response['data'].map { |r| r['id'] }).to include(<%= singular_name %>.prefixed_id)+ end+ end++ describe 'GET #show' do+ subject { get :show, params: { id: <%= singular_name %>.prefixed_id }, as: :json }++ it 'returns the <%= singular_name %>' do+ subject+ expect(response).to have_http_status(:ok)+ expect(json_response['id']).to eq(<%= singular_name %>.prefixed_id)+ end+ end++ describe 'POST #create' do+ let(:create_params) { attributes_for(:<%= singular_name %>) }++ it 'creates a <%= singular_name %>' do+ expect { post :create, params: create_params, as: :json }.to change(Spree::<%= bare_class_name %>, :count).by(1)+ expect(response).to have_http_status(:created)+ end+ end++ describe 'PATCH #update' do+ let(:update_params) { { id: <%= singular_name %>.prefixed_id }.merge(attributes_for(:<%= singular_name %>)) }++ it 'updates the <%= singular_name %>' do+ patch :update, params: update_params, as: :json+ expect(response).to have_http_status(:ok)+ end+ end++ describe 'DELETE #destroy' do+ subject { delete :destroy, params: { id: <%= singular_name %>.prefixed_id }, as: :json }++ it 'deletes the <%= singular_name %>' do+ expect { subject }.to change(Spree::<%= bare_class_name %>, :count).by(-1)+ expect(response).to have_http_status(:no_content)+ end+ end+enddiff --git a/spree/core/lib/generators/spree/api_resource/templates/admin_serializer.rb.tt b/spree/core/lib/generators/spree/api_resource/templates/admin_serializer.rb.ttnew file mode 100644index 0000000000..8f91fae4c8--- /dev/null+++ b/spree/core/lib/generators/spree/api_resource/templates/admin_serializer.rb.tt@@ -0,0 +1,11 @@+module Spree+ module Api+ module V3+ module Admin+ class <%= bare_class_name %>Serializer < V3::<%= bare_class_name %>Serializer+ attributes :created_at, :updated_at<%= ', :deleted_at' if paranoid? %>+ end+ end+ end+ end+enddiff --git a/spree/core/lib/generators/spree/api_resource/templates/factory.rb.tt b/spree/core/lib/generators/spree/api_resource/templates/factory.rb.ttnew file mode 100644index 0000000000..b1066f5efd--- /dev/null+++ b/spree/core/lib/generators/spree/api_resource/templates/factory.rb.tt@@ -0,0 +1,21 @@+FactoryBot.define do+ factory :<%= singular_name %>, class: Spree::<%= bare_class_name %> do+<% attributes.reject(&:reference?).each do |attr| -%>+<% case attr.type+ when :boolean -%>+ <%= attr.name %> { true }+<% when :integer, :decimal, :float -%>+ <%= attr.name %> { 1 }+<% when :date -%>+ <%= attr.name %> { Date.current }+<% when :datetime -%>+ <%= attr.name %> { Time.current }+<% else -%>+ sequence(:<%= attr.name %>) { |n| "<%= bare_class_name %> #{n}" }+<% end -%>+<% end -%>+<% attributes.select(&:reference?).each do |attr| -%>+ association :<%= attr.name %>+<% end -%>+ end+enddiff --git a/spree/core/lib/generators/spree/api_resource/templates/store_aliased_serializer.rb.tt b/spree/core/lib/generators/spree/api_resource/templates/store_aliased_serializer.rb.ttnew file mode 100644index 0000000000..9f02b6020e--- /dev/null+++ b/spree/core/lib/generators/spree/api_resource/templates/store_aliased_serializer.rb.tt@@ -0,0 +1,12 @@+# --store-name=<%= store_external_name %>: this serializer aliases <%= bare_class_name %>Serializer+# so the Store API surfaces the resource under a different external name+# (e.g. internal Brand → public Discount). The model and table stay as+# <%= bare_class_name %> / <%= table_name %>.+module Spree+ module Api+ module V3+ class <%= store_external_name %>Serializer < <%= bare_class_name %>Serializer+ end+ end+ end+enddiff --git a/spree/core/lib/generators/spree/api_resource/templates/store_controller.rb.tt b/spree/core/lib/generators/spree/api_resource/templates/store_controller.rb.ttnew file mode 100644index 0000000000..6493f5f076--- /dev/null+++ b/spree/core/lib/generators/spree/api_resource/templates/store_controller.rb.tt@@ -0,0 +1,31 @@+module Spree+ module Api+ module V3+ module Store+ class <%= plural_name.camelize %>Controller < ResourceController+ protected++ def model_class+ Spree::<%= class_name.demodulize %>+ end++<% if store_external_name != bare_class_name -%>+ def serializer_class+ Spree::Api::V3::<%= store_external_name %>Serializer+ end+<% else -%>+ def serializer_class+ Spree.api.<%= singular_name %>_serializer+ end+<% end -%>+<% if writable? -%>++ def permitted_params+ params.permit(<%= permitted_attribute_names.map { |a| ":#{a}" }.join(', ') %>)+ end+<% end -%>+ end+ end+ end+ end+enddiff --git a/spree/core/lib/generators/spree/api_resource/templates/store_controller_spec.rb.tt b/spree/core/lib/generators/spree/api_resource/templates/store_controller_spec.rb.ttnew file mode 100644index 0000000000..7888d17ef5--- /dev/null+++ b/spree/core/lib/generators/spree/api_resource/templates/store_controller_spec.rb.tt@@ -0,0 +1,61 @@+require 'spec_helper'++RSpec.describe Spree::Api::V3::Store::<%= plural_name.camelize %>Controller, type: :controller do+ render_views++ include_context 'API v3 Store'++ let!(:<%= singular_name %>) { create(:<%= singular_name %>) }++ before { request.headers.merge!(headers) }++ describe 'GET #index' do+ subject { get :index, as: :json }++ it 'returns <%= plural_name %>' do+ subject+ expect(response).to have_http_status(:ok)+ expect(json_response['data']).to be_an(Array)+ expect(json_response['data'].map { |r| r['id'] }).to include(<%= singular_name %>.prefixed_id)+ end+ end++ describe 'GET #show' do+ subject { get :show, params: { id: <%= singular_name %>.prefixed_id }, as: :json }++ it 'returns the <%= singular_name %>' do+ subject+ expect(response).to have_http_status(:ok)+ expect(json_response['id']).to eq(<%= singular_name %>.prefixed_id)+ end+ end+<% if writable? -%>++ describe 'POST #create' do+ let(:create_params) { attributes_for(:<%= singular_name %>) }++ it 'creates a <%= singular_name %>' do+ expect { post :create, params: create_params, as: :json }.to change(Spree::<%= bare_class_name %>, :count).by(1)+ expect(response).to have_http_status(:created)+ end+ end++ describe 'PATCH #update' do+ let(:update_params) { { id: <%= singular_name %>.prefixed_id }.merge(attributes_for(:<%= singular_name %>)) }++ it 'updates the <%= singular_name %>' do+ patch :update, params: update_params, as: :json+ expect(response).to have_http_status(:ok)+ end+ end++ describe 'DELETE #destroy' do+ subject { delete :destroy, params: { id: <%= singular_name %>.prefixed_id }, as: :json }++ it 'deletes the <%= singular_name %>' do+ expect { subject }.to change(Spree::<%= bare_class_name %>, :count).by(-1)+ expect(response).to have_http_status(:no_content)+ end+ end+<% end -%>+enddiff --git a/spree/core/lib/generators/spree/api_resource/templates/store_serializer.rb.tt b/spree/core/lib/generators/spree/api_resource/templates/store_serializer.rb.ttnew file mode 100644index 0000000000..0e5a60d814--- /dev/null+++ b/spree/core/lib/generators/spree/api_resource/templates/store_serializer.rb.tt@@ -0,0 +1,14 @@+<% typelizable = attributes.reject(&:reference?).select { |a| %i[boolean integer decimal float].include?(a.type) } -%>+module Spree+ module Api+ module V3+ class <%= bare_class_name %>Serializer < BaseSerializer+<% if typelizable.any? -%>+ typelize <%= typelizable.map { |a| "#{a.name}: :#{a.type == :boolean ? 'boolean' : 'number'}" }.join(', ') %>++<% end -%>+ attributes <%= (['id'] + permitted_attribute_names).map { |a| ":#{a}" }.join(', ') %>+ end+ end+ end+end