spree_api 6.0.2 → 6.0.4

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

@@ -0,0 +1,110 @@
+require 'spree/api/testing_support/agent_tools'
+
+# The contract between an engine's admin endpoints and the agent tools built
+# from them. Core includes it, and so does every extension that adds admin
+# endpoints:
+#
+#   require 'spree/api/testing_support/agent_tools_contract'
+#
+#   RSpec.describe 'agent tools' do
+#     it_behaves_like 'an engine whose admin writes are agent tools', MyExtension::Engine
+#   end
+#
+# An admin write cannot land without an operation describing it, an opt-out
+# without its reason, or two operations claiming one tool name.
+#
+# See docs/plans/6.0-agent-tools-from-openapi.md.
+RSpec.shared_examples 'an engine whose admin writes are agent tools' do |engine|
+  operations = Spree::Api::AgentOperations
+  root = engine.root.to_s
+  defined_here = lambda do |controller|
+    controller && Object.const_source_location(controller.name)&.first&.start_with?(root)
+  end
+
+  # The admin operations this engine's own controllers serve.
+  let(:engine_candidates) do
+    operations.candidates.select { |candidate| defined_here.call(candidate.dig(:route, :controller)) }
+  end
+
+  let(:engine_routes) do
+    operations.admin_routes.filter_map do |route|
+      next unless operations::WRITE_VERBS.include?(route[:verb]) && !operations::CRUD_ACTIONS.include?(route[:action])
+
+      [route[:verb], route[:path]] if defined_here.call(route[:controller])
+    end.uniq
+  end
+
+  # The tool name each listed action derives, before collisions are settled.
+  let(:included_names) do
+    engine_candidates.select { |candidate| operations.disposition(candidate) == :included }.
+      map { |candidate| operations.tool_name(candidate) }
+  end
+
+  it 'documents every admin action its controllers serve' do
+    paths = Spree::Api::AdminDocument.document['paths'] || {}
+    undocumented = engine_routes.reject { |verb, path| paths.dig(path, verb) }.
+                   map { |verb, path| "#{verb.upcase} #{path}" }
+
+    expect(undocumented).to be_empty, <<~MESSAGE
+      These admin actions have no operation in the engine's OpenAPI document, so no
+      agent tool and no API reference describes them:
+
+        #{undocumented.join("\n  ")}
+
+      Write an rswag integration spec for each, then regenerate the document.
+    MESSAGE
+  end
+
+  it 'gives every opt-out a reason' do
+    unexplained = engine_candidates.filter_map do |candidate|
+      operation = candidate[:operation]
+      next unless operation[operations::AGENT_KEY] == false && operation[operations::REASON_KEY].blank?
+
+      "#{candidate[:verb].upcase} #{candidate[:path]}"
+    end
+
+    expect(unexplained).to be_empty
+  end
+
+  # Across every engine, not only this one: an extension's action deriving
+  # a core name would otherwise lose to the shallower path, quietly.
+  it 'derives a distinct tool name for every action' do
+    every_name = operations.candidates.select { |candidate| operations.disposition(candidate) == :included }.
+                 map { |candidate| operations.tool_name(candidate) }
+    duplicated = every_name.tally.select { |name, count| count > 1 && included_names.include?(name) }.keys
+
+    expect(duplicated).to be_empty, "Give these operations an operationId: #{duplicated.join(', ')}"
+  end
+
+  # A hand-registered tool keeps its name, so an operation deriving the same
+  # one would vanish from every agent surface.
+  it 'claims no name a hand-written tool already has' do
+    hand_written = Spree.admin_agent_tools.send(:registered_classes).map(&:tool_name)
+
+    expect(included_names & hand_written).to be_empty
+  end
+
+  it 'merges its document into core\'s without a conflict' do
+    expect(Spree::Api::AdminDocument.conflicts).to be_empty
+  end
+
+  it 'names every tool the way MCP accepts' do
+    catalog = Spree::AgentTools::OperationCatalog
+    invalid = (catalog.all + catalog.aliases).map(&:name).
+              reject { |name| name.match?(/\A[a-zA-Z0-9_-]{1,64}\z/) }
+
+    expect(invalid).to be_empty
+  end
+
+  it 'gives every tool a summary and a permission the catalog knows' do
+    faults = included_names.filter_map do |name|
+      entry = Spree::AgentTools::OperationCatalog.find(name)
+      next "#{name}: not registered" if entry.nil?
+      next "#{name}: no summary" if entry.summary.blank?
+
+      "#{name}: unknown permission #{entry.permission}" unless Spree.permissions.key?(entry.permission)
+    end
+
+    expect(faults).to be_empty
+  end
+end

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

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+# The OpenAPI specs in docs/api-reference/ embed real response bodies captured
+# while the integration suite runs, so anything the suite generates at random
+# lands in a checked-in file. Two runs of unchanged code used to produce a
+# ~1,800 line diff, which buried real API changes in noise during review.
+#
+# Under OPENAPI=true (set by the swaggerize rake task) every source of that
+# noise is pinned, so regenerating the specs yields a byte-identical file
+# unless the API itself changed. Nothing here is loaded by a normal spec run —
+# the suite keeps its random names and real clock.
+if ENV['OPENAPI'] == 'true'
+  require 'securerandom'
+  require 'digest/md5'
+  require 'ffaker'
+
+  module Spree
+    module OpenAPIDeterminism
+      # The instant every generated example is stamped with. Anything derived
+      # from it — an expiry fourteen days out, a promotion window — lands on a
+      # stable value too, so a whole run reduces to this one timestamp. Bump it
+      # only when the dates in the published examples start looking stale; each
+      # bump rewrites every timestamp in the checked-in specs.
+      FROZEN_TIME = Time.utc(2026, 1, 15, 12, 0, 0)
+
+      # Base seed for the two pseudo-random generators in play: Ruby's global
+      # one, which Kernel.rand draws from, and FFaker's own, which is separate
+      # and needs seeding through its own API. Both are mixed with the example's
+      # identity for the same reason the token seeds are: a run-wide constant
+      # would hand every example the same "random" name and email, and the
+      # unique ones then collide on a real index.
+      RANDOM_SEED = 20_260_115
+
+      # Signing secret for the JWTs shown in the examples. It signs nothing
+      # real — these tokens are documentation, generated against a throwaway
+      # dummy app — but it has to be the same everywhere for the signatures
+      # to match across machines.
+      JWT_SECRET = 'openapi-example-signing-secret'
+
+      # SecureRandom bypasses the global PRNG (it reads from the OS), so seeding
+      # alone leaves API keys, invitation tokens and JWT ids churning. These
+      # counter-backed replacements produce values with the right shape and
+      # length for anything that stores or displays them.
+      module PredictableSecureRandom
+        HEX_ALPHABET = '0123456789abcdef'
+        BASE58_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'
+        BASE36_ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyz'
+        URL_SAFE_ALPHABET = "#{BASE36_ALPHABET}ABCDEFGHIJKLMNOPQRSTUVWXYZ-_"
+
+        class << self
+          # Values must be unique across the whole run (they back columns with
+          # unique indexes, such as a store's setup token) while still being
+          # reproducible. Deriving the seed from the current example's id plus a
+          # per-example counter gives both: unique because no two examples share
+          # an id, reproducible because an example's id does not change between
+          # runs, and stable under edits because adding one spec cannot shift
+          # the values another spec produces.
+          def scope!(example_key)
+            @example_key = example_key
+            @sequence = 0
+          end
+
+          # Digest rather than String#hash: Ruby randomizes String#hash per
+          # process, which is exactly the churn this file exists to remove.
+          def next_seed
+            @sequence = (@sequence || 0) + 1
+            Digest::MD5.hexdigest("#{@example_key}/#{@sequence}")[0, 15].to_i(16)
+          end
+
+          def string_from(alphabet, length)
+            generator = Random.new(next_seed)
+            Array.new(length) { alphabet[generator.rand(alphabet.length)] }.join
+          end
+        end
+
+        # Callers pass nil to mean "the default length", so every override
+        # normalizes it rather than doing arithmetic on it.
+        def hex(length = nil)
+          PredictableSecureRandom.string_from(HEX_ALPHABET, (length || 16) * 2)
+        end
+
+        def base58(length = nil)
+          PredictableSecureRandom.string_from(BASE58_ALPHABET, length || 16)
+        end
+
+        def base36(length = nil)
+          PredictableSecureRandom.string_from(BASE36_ALPHABET, length || 16)
+        end
+
+        def alphanumeric(length = nil, chars: nil)
+          return super if chars
+
+          PredictableSecureRandom.string_from(BASE58_ALPHABET, length || 16)
+        end
+
+        def urlsafe_base64(length = nil, _padding = false)
+          PredictableSecureRandom.string_from(URL_SAFE_ALPHABET, ((length || 16) * 4 / 3.0).ceil)
+        end
+
+        def uuid
+          digits = PredictableSecureRandom.string_from(HEX_ALPHABET, 32)
+          [digits[0, 8], digits[8, 4], "4#{digits[13, 3]}", "a#{digits[17, 3]}", digits[20, 12]].join('-')
+        end
+
+        def bytes(length)
+          PredictableSecureRandom.string_from(HEX_ALPHABET, (length || 16) * 2)[0, length || 16]
+        end
+      end
+    end
+  end
+
+  SecureRandom.singleton_class.prepend(Spree::OpenAPIDeterminism::PredictableSecureRandom)
+
+  RSpec.configure do |config|
+    config.before do
+      travel_to(Spree::OpenAPIDeterminism::FROZEN_TIME)
+    end
+
+    # Reset before each example rather than once for the run, so a value shown
+    # in one example does not depend on how many records the examples before it
+    # happened to create. Without this, adding a spec shifts every random value
+    # generated after it and the diff spreads across unrelated endpoints.
+    #
+    # FactoryBot's own sequences are deliberately left alone: they already count
+    # from one per process, so they are stable, and rewinding them mid-run would
+    # hand out an SKU or email that another example already claimed.
+    config.before do |example|
+      example_key = example.metadata[:full_description]
+      example_seed = Spree::OpenAPIDeterminism::RANDOM_SEED ^ Digest::MD5.hexdigest(example_key)[0, 15].to_i(16)
+
+      srand(example_seed)
+      FFaker::Random.seed = example_seed
+      Spree::OpenAPIDeterminism::PredictableSecureRandom.scope!(example_key)
+
+      # The examples include signed JWTs. Their payloads are already stable
+      # (a frozen clock fixes `exp`, the SecureRandom override fixes `jti`),
+      # but the signature also depends on the signing secret, which otherwise
+      # falls through to the dummy app's `secret_key_base` — generated when
+      # that app is built and so different on every machine. Without this the
+      # specs reproduce for whoever generated them and for nobody else.
+      #
+      # Set per example, not once for the suite: the suite resets Spree's
+      # preferences before every example, which would wipe a one-off value.
+      Spree::Api::Config[:jwt_secret_key] = Spree::OpenAPIDeterminism::JWT_SECRET
+    end
+  end
+end

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

@@ -0,0 +1,99 @@
+require 'spree/api/openapi/filter_documentation'
+
+module Spree
+  module Api
+    module TestingSupport
+      # Documents a list endpoint's filters from the model allowlists, so no
+      # integration spec lists `q[...]` parameters by hand.
+      #
+      #   path '/api/v3/admin/orders' do
+      #     get 'List orders' do
+      #       filter_parameters_for search: 'Order number, purchase order or customer name'
+      #
+      # Adds `q[search]` first and the endpoint's other scopes as named query
+      # parameters, one `q` parameter for attribute filters, the attribute table
+      # above the endpoint (`x-mint.content`), and the machine-readable
+      # `x-spree-filters` extension. Every table the filters reach is registered
+      # under the spec's `components.x-spree-filter-tables`, which is what the SDK
+      # filter types are generated from.
+      module FilterParameters
+        FILTER_TABLES_KEY = :'x-spree-filter-tables'
+        FILTER_PREDICATES_KEY = :'x-spree-filter-predicates'
+        # What `q[search]` matches on models whose search is written by hand rather
+        # than declared with `search_by` (which describes itself).
+        SEARCH_DESCRIPTIONS = {
+          'Product' => 'Matches product name or variant SKU (partial, case-insensitive), and the store\'s searchable custom fields.',
+          'Variant' => 'Matches SKU, option value or product name (partial, case-insensitive; at least three characters).',
+          'Price' => 'Matches the variant\'s SKU, option value or product name, as variant search does.',
+          'Customer' => 'Matches email, first name, last name or full name (partial, case-insensitive).',
+          'Order' => 'Matches order number or purchase order number (partial), the billing first or last name, or the exact email.'
+        }.freeze
+
+        STORE_QUERYING_PAGE = '/api-reference/store-api/querying#which-filters-an-endpoint-accepts'
+        ADMIN_QUERYING_PAGE = '/api-reference/admin-api/querying#which-filters-an-endpoint-accepts'
+
+        # @param controller_class [Class, nil] the controller serving the list;
+        #   resolved from the path when omitted
+        # @param search [String, nil] what `q[search]` matches, required when the
+        #   model's search is not declared with `search_by`
+        # @param scopes [Hash{Symbol => String}] descriptions of other scopes
+        def filter_parameters_for(controller_class = nil, search: nil, scopes: {})
+          endpoint = Spree::Api::V3::FilterTable.for(controller_class || filter_controller_for_path)
+          docs = Spree::Api::OpenAPI::FilterDocumentation.new(
+            endpoint, search: search || SEARCH_DESCRIPTIONS[endpoint.table.name], scopes: scopes,
+            querying_path: spec_name.to_s.end_with?('store.yaml') ? STORE_QUERYING_PAGE : ADMIN_QUERYING_PAGE
+          )
+
+          parameter name: :q, in: :query, required: false, style: :deepObject, explode: true,
+                    schema: { type: :object, additionalProperties: true },
+                    description: 'Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list.'
+          insert_before_query_parameters(docs.parameters)
+
+          metadata[:operation][:'x-mint'] = (metadata[:operation][:'x-mint'] || {}).merge(content: docs.content)
+          metadata[:operation][:'x-spree-filters'] = endpoint.to_h
+          register_filter_tables(endpoint.tables)
+        end
+
+        private
+
+        def filter_controller_for_path
+          path = metadata[:path_item][:template].gsub(/\{[^}]+\}/, 'x1')
+          route = Rails.application.routes.recognize_path(path, method: :get)
+          "#{route[:controller]}_controller".camelize.constantize
+        end
+
+        # rswag routes an operation with no document named to the first one.
+        def spec_name
+          metadata[:openapi_spec] || metadata[:swagger_doc] || RSpec.configuration.openapi_specs.keys.first
+        end
+
+        # `q[search]` and the scopes go ahead of `page`, `sort` and the rest, so the
+        # filter a reader reaches for first is the first one listed.
+        def insert_before_query_parameters(parameters)
+          existing = metadata[:operation][:parameters] ||= []
+          index = existing.index { |parameter| parameter[:in] == :query } || existing.size
+          existing.insert(index, *parameters)
+        end
+
+        def register_filter_tables(tables)
+          spec = RSpec.configuration.openapi_specs.fetch(spec_name)
+          components = spec[:components] ||= {}
+          registered = components[FILTER_TABLES_KEY] || {}
+
+          tables.each do |name, table|
+            definition = table.to_h
+            if registered.key?(name) && registered[name] != definition
+              raise "Two filter tables are named #{name} in #{spec_name}; give one of the models a distinct api_type"
+            end
+
+            registered[name] = definition
+          end
+
+          # Sorted so the written spec does not depend on the order specs ran in.
+          components[FILTER_TABLES_KEY] = registered.sort.to_h
+          components[FILTER_PREDICATES_KEY] = Spree::Api::V3::FilterPredicates::BY_KIND
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,233 @@
+require 'spree/api/testing_support/v3/base'
+require 'spree/api/testing_support/agent_tools'
+require 'spree/api/testing_support/deterministic_openapi'
+require 'spree/api/testing_support/filter_parameters'
+require 'spree/api/testing_support/sdk_method'
+
+module Spree
+  module Api
+    module TestingSupport
+      # Documents a write endpoint's request body from the controller's
+      # `request_params` declaration, so no integration spec describes a body by hand.
+      #
+      #   path '/api/v3/admin/products' do
+      #     post 'Create a product' do
+      #       request_body_for
+      #
+      # The body references the `<Resource>CreateParams` / `<Resource>UpdateParams`
+      # component, registered with every shared shape it uses under the spec's
+      # `components.schemas`. The SDK request types are generated from those
+      # components.
+      module RequestBody
+        # @param action [Symbol, nil] the controller action; read from the route
+        #   when omitted
+        # @param controller [Class, nil] resolved from the path when omitted
+        # @param required [Boolean] false for an endpoint that accepts no body
+        def request_body_for(action = nil, controller: nil, required: true)
+          route = request_body_route
+          action ||= route[:action].to_sym
+          controller ||= "#{route[:controller]}_controller".camelize.constantize
+          schema = controller.request_params_schema(action)
+          raise "#{controller.name} does not declare request_params for #{action}" unless schema
+
+          name = schema.component_name(action)
+          register_request_schema(name, schema.json_schema(action.in?(%i[create update]) ? action : nil))
+          schema.shapes.each { |shape| register_request_schema(shape.name, shape.json_schema) }
+          schema.code_lists.each { |list_name, definition| register_request_schema(list_name, definition) }
+
+          parameter name: :body, in: :body, required: required, schema: { '$ref': "#/components/schemas/#{name}" }
+        end
+
+        # Documents a shape a read endpoint takes as query parameters, and publishes
+        # it as a component so the SDKs generate one type for it.
+        #
+        # @param shape [Spree::Api::V3::RequestSchema] a named shape
+        def query_parameters_for(shape)
+          register_request_schema(shape.name, shape.json_schema)
+          shape.shapes.each { |nested| register_request_schema(nested.name, nested.json_schema) }
+          shape.code_lists.each { |list_name, definition| register_request_schema(list_name, definition) }
+
+          shape.json_schema[:properties].each do |name, property|
+            parameter name: name, in: :query, required: false, description: property[:description],
+                      schema: property.except(:description)
+          end
+        end
+
+        private
+
+        def request_body_route
+          path = metadata[:path_item][:template].gsub(/\{[^}]+\}/, 'x1')
+          Rails.application.routes.recognize_path(path, method: metadata[:operation][:verb])
+        end
+
+        def register_request_schema(name, definition)
+          # rswag routes an operation with no document named to the first one.
+          specs = RSpec.configuration.openapi_specs
+          spec = specs.fetch(metadata[:openapi_spec] || metadata[:swagger_doc] || specs.keys.first)
+          schemas = (spec[:components] ||= {})[:schemas] ||= {}
+          definition = definition.deep_stringify_keys
+
+          if schemas.key?(name) && schemas[name].deep_stringify_keys != definition
+            raise "Two request schemas are named #{name}; " \
+                  'name one of the request_params declarations or shapes differently'
+          end
+
+          schemas[name] = definition
+          # Request schemas follow the response ones, sorted, so the written spec
+          # does not depend on the order specs ran in.
+          request, response = schemas.partition { |key, _| key.to_s.end_with?('Params') }
+          spec[:components][:schemas] = response.to_h.merge(request.sort_by { |key, _| key.to_s }.to_h)
+        end
+      end
+
+      # Appends a `**Required scope:**` line to the operation description, to
+      # surface scope requirements in the rendered docs without inventing a
+      # custom OpenAPI extension.
+      #
+      #   admin_scope :read, :orders
+      #   admin_scope :write, :customers
+      module AdminScope
+        def admin_scope(action, resource)
+          admin_scope_note("`#{action}_#{resource}`")
+        end
+
+        # Free-form variant for endpoints whose required scope is resolved at
+        # request time (e.g. exports — gated by the exported resource's scope).
+        def admin_scope_note(text)
+          line = "**Required scope:** #{text} (for API-key authentication)."
+          existing = metadata[:operation][:description].to_s
+          metadata[:operation][:description] = existing.empty? ? line : "#{existing}\n\n#{line}"
+        end
+      end
+
+      # What every admin operation in an rswag spec repeats, in one line: the
+      # content types, the two ways to authenticate, the scope note in the
+      # description, and a signed-in admin and secret key to call it with.
+      #
+      #   patch 'Send a quote' do
+      #     tags 'Quotes'
+      #     admin_operation :write, :quotes, description: <<~DESC
+      #       Sends the quote to the buyer. Use it once the prices are final.
+      #     DESC
+      #     request_body_for
+      #
+      #     response('200', 'sent') { run_test! }
+      #   end
+      #
+      # Pass the description here, or call it after `description`: the scope
+      # note is appended to whatever the description is at that point. A
+      # response block overrides either credential with its own `let`. The
+      # credentials come from the 'API v3 Admin' shared context, which
+      # Openapi.configure includes in every request spec.
+      module AdminOperation
+        BODY_VERBS = %i[post patch put].freeze
+
+        # @param kind [Symbol] :read or :write
+        # @param resource [Symbol] the controller's scoped resource
+        # @param description [String, nil]
+        # @return [void]
+        def admin_operation(kind, resource, description: nil)
+          verb = metadata[:operation][:verb].to_sym
+          consumes 'application/json' if BODY_VERBS.include?(verb)
+          produces 'application/json'
+          security [api_key: [], bearer_auth: []]
+          parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+          parameter name: :Authorization, in: :header, type: :string, required: true
+
+          self.description(description.strip) if description
+          admin_scope(kind, resource)
+
+          let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+          let(:Authorization) { "Bearer #{admin_jwt_token}" }
+        end
+      end
+
+      # What an extension needs to generate the `openapi/admin.yaml` its gem
+      # ships, documenting its Admin API endpoints the way core documents its
+      # own, and with `store_title:` an `openapi/store.yaml` for its Store API
+      # endpoints. The extension can build its API docs or a client from the
+      # files (`spree sdk types`). In the extension's swagger helper:
+      #
+      #   require 'rswag/specs'
+      #   require 'spree/api/testing_support/openapi'
+      #
+      #   RSpec.configure do |config|
+      #     Spree::Api::TestingSupport::Openapi.configure(
+      #       config, engine: MyExtension::Engine, title: 'My Extension Admin API'
+      #     )
+      #   end
+      #
+      # A Store API spec names its document and authenticates as a customer:
+      #
+      #   path '/api/v3/store/quotes' do
+      #     get 'List quotes', openapi_spec: 'openapi/store.yaml' do
+      #       include_context 'API v3 Store authenticated'
+      #
+      # and in its Rakefile, `require 'spree/api/testing_support/openapi_tasks'`
+      # for `rake spree:openapi:generate`.
+      module Openapi
+        HELPERS = [RequestBody, FilterParameters, AdminScope, AdminOperation, AgentTools, SdkMethod].freeze
+
+        class << self
+          # @param config [RSpec::Core::Configuration]
+          # @param engine [Class<Rails::Engine>]
+          # @param title [String]
+          # @param description [String, nil]
+          # @param store_title [String, nil] also writes `openapi/store.yaml`,
+          #   for an extension with Store API endpoints
+          # @return [void]
+          def configure(config, engine:, title:, description: nil, store_title: nil)
+            config.openapi_root = engine.root.to_s
+            # Admin first: rswag writes an operation that names no document there.
+            config.openapi_specs = { 'openapi/admin.yaml' => admin_document(title, description) }
+            config.openapi_specs['openapi/store.yaml'] = store_document(store_title) if store_title
+            config.openapi_format = :yaml
+            HELPERS.each { |helper| config.extend helper, type: :request }
+            # The admin and secret key admin_operation authenticates with.
+            config.include_context 'API v3 Admin', type: :request
+          end
+
+          # The skeleton of an extension's store document: the same security
+          # schemes as core's Store API.
+          #
+          # @return [Hash]
+          def store_document(title)
+            {
+              openapi: '3.0.3',
+              info: { title: title, version: 'v3' },
+              paths: {},
+              components: {
+                securitySchemes: {
+                  api_key: { type: :apiKey, name: 'x-spree-api-key', in: :header,
+                             description: 'Publishable API key for store access' },
+                  bearer_auth: { type: :http, scheme: :bearer, bearerFormat: 'JWT',
+                                 description: 'JWT token for authenticated customers' }
+                }
+              }
+            }
+          end
+
+          # The skeleton of an extension's admin document: the same security
+          # schemes as core's, so its operations authenticate the same way.
+          #
+          # @return [Hash]
+          def admin_document(title, description = nil)
+            {
+              openapi: '3.0.3',
+              info: { title: title, version: 'v3', description: description }.compact,
+              paths: {},
+              components: {
+                securitySchemes: {
+                  api_key: { type: :apiKey, name: 'x-spree-api-key', in: :header,
+                             description: 'Secret API key for admin access' },
+                  bearer_auth: { type: :http, scheme: :bearer, bearerFormat: 'JWT',
+                                 description: 'JWT token for admin user authentication' }
+                }
+              }
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# `rake spree:openapi:generate` for an extension or a Spree application: runs
+# its integration specs through rswag and writes the `openapi/admin.yaml` it
+# ships, and `openapi/store.yaml` when it documents Store API endpoints. Under
+# OPENAPI=true the run is reproducible (see deterministic_openapi.rb), so a
+# diff in a file means the API changed.
+#
+# RSpec is started only when the task runs, so a Rakefile that loads this
+# keeps working in a bundle without rspec-core. Defined once, however many
+# times it is loaded: a second definition would run the specs twice.
+unless Rake::Task.task_defined?('spree:openapi:generate')
+  namespace :spree do
+    namespace :openapi do
+      desc 'Generate the openapi/*.yaml documents from the integration specs here'
+      task :generate do
+        pattern = ENV.fetch('PATTERN', 'spec/integration/**/*_spec.rb')
+        ENV['OPENAPI'] = 'true'
+        ruby '-S', 'rspec', '--pattern', pattern, '--format', 'Rswag::Specs::SwaggerFormatter', '--order', 'defined'
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+module Spree
+  module Api
+    module TestingSupport
+      # rswag helper for what an operation is called in the SDK client
+      # `spree sdk generate` writes for an extension. By default a method is
+      # named after the path (`PATCH /quotes/{id}/send` → `quotes.send`), and
+      # an `operationId` renames it, but the `operationId` also names the
+      # operation's agent tool. This names the SDK method alone:
+      #
+      #   delete 'Remove a file from a quote' do
+      #     sdk_method :remove_attachment                    # quotes.removeAttachment
+      #   end
+      #
+      #   post 'Upload a file for a quote request' do
+      #     sdk_method :presign_attachment, namespace: :quotes  # not carts.…
+      #   end
+      #
+      # See docs/plans/6.0-sdk-extensions.md.
+      module SdkMethod
+        METHOD_KEY = :'x-spree-sdk-method'
+        NAMESPACE_KEY = :'x-spree-sdk-namespace'
+
+        # @param name [Symbol, String] the method, snake_case or camelCase
+        # @param namespace [Symbol, String, nil] the client namespace it goes in,
+        #   instead of the path's resource
+        # @return [void]
+        def sdk_method(name, namespace: nil)
+          metadata[:operation][METHOD_KEY] = name.to_s
+          metadata[:operation][NAMESPACE_KEY] = namespace.to_s if namespace
+        end
+      end
+    end
+  end
+end