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.

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.yml
index 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.rb
new file mode 100644
index 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
+end
diff --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.tt
new file mode 100644
index 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
+end
diff --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.tt
new file mode 100644
index 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
+end
diff --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.tt
new file mode 100644
index 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
+end
diff --git a/spree/core/lib/generators/spree/api_resource/templates/factory.rb.tt b/spree/core/lib/generators/spree/api_resource/templates/factory.rb.tt
new file mode 100644
index 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
+end
diff --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.tt
new file mode 100644
index 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
+end
diff --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.tt
new file mode 100644
index 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
+end
diff --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.tt
new file mode 100644
index 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 -%>
+end
diff --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.tt
new file mode 100644
index 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