action_spec 1.2.0 → 1.4.0

data/lib/action_spec/doc.rb

@@ -8,6 +8,8 @@ module ActionSpec
     extend ActiveSupport::Concern
 
     class_methods do
+      DryEntry = Struct.new(:block, :options, keyword_init: true)
+
       def action_specs
         @action_specs ||= begin
           parent = superclass.respond_to?(:action_specs) ? superclass.action_specs : {}
@@ -18,20 +20,24 @@ module ActionSpec
       def dry_blocks
         @dry_blocks ||= begin
           parent = superclass.respond_to?(:dry_blocks) ? superclass.dry_blocks : {}
-          parent.transform_values { |blocks| blocks.map(&:dup) }
+          parent.transform_values do |entries|
+            entries.map { |entry| DryEntry.new(block: entry.block, options: entry.options.deep_dup) }
+          end
         end
       end
 
       def doc(action_or_summary = nil, summary = nil, **options, &block)
         action_name, endpoint_summary = normalize_doc_arguments(action_or_summary, summary)
         action_name ||= infer_action_name(caller_locations(1, 1).first)
-        endpoint = Endpoint.new(action_name, summary: endpoint_summary, options:)
-        action_specs[action_name.to_sym] = apply_dry_blocks(endpoint).apply(block || proc {})
+        endpoint = Endpoint.new(action_name, summary: endpoint_summary, options: {})
+        endpoint = apply_dry_blocks(endpoint)
+        endpoint.options.merge!(options)
+        action_specs[action_name.to_sym] = endpoint.apply(block || proc {})
       end
 
-      def doc_dry(actions = :all, &block)
+      def doc_dry(actions = :all, **options, &block)
         Array(actions).each do |action|
-          (dry_blocks[action.to_sym] ||= []) << block
+          (dry_blocks[action.to_sym] ||= []) << DryEntry.new(block:, options:)
         end
       end
       alias api_dry doc_dry
@@ -49,8 +55,9 @@ module ActionSpec
         end
 
         def apply_dry_blocks(endpoint)
-          [*dry_blocks[:all], *dry_blocks[endpoint.action]].compact.each do |dry_block|
-            endpoint.apply(dry_block)
+          [*dry_blocks[:all], *dry_blocks[endpoint.action]].compact.each do |entry|
+            endpoint.options.merge!(entry.options)
+            endpoint.apply(entry.block) if entry.block
           end
           endpoint
         end

data/lib/action_spec/open_api/generator.rb

@@ -8,8 +8,25 @@ module ActionSpec
           document = new(application:, routes:, title:, version:, server_url:).call
 
           FileUtils.mkdir_p(File.dirname(output))
-          File.write(output, YAML.dump(document))
+          File.write(output, pretty_yaml(plain_data(document)))
         end
+
+        private
+
+          def pretty_yaml(document)
+            YAML.dump(document).gsub(/^(\s*)"\/([^"]+)":$/, '\1/\2:')
+          end
+
+          def plain_data(value)
+            case value
+            when Array
+              value.map { |item| plain_data(item) }
+            when Hash
+              value.each_with_object({}) { |(key, item), hash| hash[key] = plain_data(item) }
+            else
+              value
+            end
+          end
       end
 
       def initialize(application: nil, routes: nil, title: nil, version: nil, server_url: nil)
@@ -55,7 +72,7 @@ module ActionSpec
 
             hash[path] ||= ActiveSupport::OrderedHash.new
             route_verbs(route).each do |verb|
-              hash[path][verb] = Operation.new(endpoint).build
+              hash[path][verb] = Operation.new(endpoint, controller_path: controller.controller_path).build
             end
           end
         end

data/lib/action_spec/open_api/operation.rb

@@ -3,14 +3,17 @@
 module ActionSpec
   module OpenApi
     class Operation
-      def initialize(endpoint)
+      def initialize(endpoint, controller_path:)
         @endpoint = endpoint
+        @controller_path = controller_path
         @schema = Schema.new
       end
 
       def build
         {
           "summary" => endpoint.summary.presence,
+          "operationId" => operation_id,
+          "tags" => tags,
           "parameters" => parameters.presence,
           "requestBody" => schema.request_body(endpoint.request),
           "responses" => responses
@@ -19,7 +22,23 @@ module ActionSpec
 
       private
 
-        attr_reader :endpoint, :schema
+        attr_reader :endpoint, :controller_path, :schema
+
+        def tags
+          [endpoint.options[:tag].presence || controller_path.presence].compact
+        end
+
+        def operation_id
+          [primary_tag, endpoint.action].compact.join("_")
+        end
+
+        def primary_tag
+          resolved_tag&.to_s&.tr("/", "_")
+        end
+
+        def resolved_tag
+          endpoint.options[:tag].presence || controller_path.presence
+        end
 
         def parameters
           %i[path query header cookie].flat_map do |location|
@@ -33,7 +52,7 @@ module ActionSpec
           return { "200" => { "description" => "OK" } } if endpoint.responses.empty?
 
           endpoint.responses.each_with_object(ActiveSupport::OrderedHash.new) do |(code, response), hash|
-            hash[code] = { "description" => response.description.presence || "OK" }
+            hash[code] = schema.response(response)
           end
         end
     end

data/lib/action_spec/open_api/schema.rb

@@ -36,7 +36,16 @@ module ActionSpec
         end
         return if content.empty?
 
-        { "content" => content }
+        { "content" => content }.tap do |body|
+          body["required"] = true if request.body_required?
+        end
+      end
+
+      def response(response)
+        {
+          "description" => response.description.presence || "OK",
+          "content" => response_content(response).presence
+        }.compact
       end
 
       def schema_for(schema)
@@ -50,6 +59,29 @@ module ActionSpec
 
       private
 
+        def response_content(response)
+          response.media_types.each_with_object(ActiveSupport::OrderedHash.new) do |(media_type, content), hash|
+            normalized = response_media_type_content(content)
+            next if normalized.blank?
+
+            hash[MEDIA_TYPE_MAP.fetch(media_type, media_type.to_s)] = normalized
+          end
+        end
+
+        def response_media_type_content(content)
+          {}.tap do |definition|
+            if (schema = content[:schema] || infer_schema_from_examples(content)).present?
+              definition["schema"] = schema_for(schema)
+            end
+
+            if (examples = normalize_response_examples(content[:examples])).present?
+              definition["examples"] = examples
+            elsif (example = normalize_response_example(content[:example])).present?
+              definition["example"] = example
+            end
+          end.presence
+        end
+
         def parameter_name(field, location)
           return field.name.to_s if location != :header
 
@@ -105,16 +137,23 @@ module ActionSpec
 
         def apply_common_options(definition, schema)
           definition["description"] = schema.description if schema.description.present?
-          definition["default"] = schema.default unless schema.default.respond_to?(:call) || schema.default.nil?
+          apply_literal_option(definition, "default", schema.default) unless schema.default.respond_to?(:call)
           definition["enum"] = schema.enum if schema.enum.present?
           definition["pattern"] = regex_source(schema.pattern) if schema.pattern.present?
           apply_length(definition, schema.length, definition["type"])
-          definition["example"] = schema.example if schema.example.present?
-          definition["examples"] = schema.examples if schema.examples.present?
+          apply_literal_option(definition, "example", schema.example)
+          apply_literal_option(definition, "examples", schema.examples)
           apply_range(definition, schema.range)
           definition
         end
 
+        def apply_literal_option(definition, key, value)
+          normalized = openapi_literal(value)
+          return if normalized.nil? || normalized.equal?(invalid_openapi_literal)
+
+          definition[key] = normalized
+        end
+
         def apply_range(definition, range)
           return if range.blank?
 
@@ -166,6 +205,104 @@ module ActionSpec
         def regex_source(pattern)
           pattern.is_a?(Regexp) ? pattern.source : pattern.to_s
         end
+
+        def openapi_literal(value)
+          case value
+          when nil, String, Integer, Float, TrueClass, FalseClass
+            value
+          when Array
+            normalized = value.map { |item| openapi_literal(item) }
+            return invalid_openapi_literal if normalized.any? { |item| item.equal?(invalid_openapi_literal) }
+
+            normalized
+          when Hash
+            value.each_with_object(ActiveSupport::OrderedHash.new) do |(key, item), normalized|
+              item = openapi_literal(item)
+              return invalid_openapi_literal if item.equal?(invalid_openapi_literal)
+
+              normalized[key.to_s] = item
+            end
+          else
+            invalid_openapi_literal
+          end
+        end
+
+        def invalid_openapi_literal
+          @invalid_openapi_literal ||= Object.new.freeze
+        end
+
+        def normalize_response_example(example)
+          normalized = openapi_literal(example)
+          return if normalized.nil? || normalized.equal?(invalid_openapi_literal)
+
+          normalized
+        end
+
+        def normalize_response_examples(examples)
+          return if examples.blank?
+
+          examples.each_with_object(ActiveSupport::OrderedHash.new) do |(name, value), hash|
+            normalized = openapi_literal(value)
+            next if normalized.nil? || normalized.equal?(invalid_openapi_literal)
+
+            hash[name.to_s] = { "value" => normalized }
+          end.presence
+        end
+
+        def infer_schema_from_examples(content)
+          values =
+            if content[:examples].present?
+              content[:examples].values
+            elsif !content[:example].nil?
+              [content[:example]]
+            else
+              []
+            end
+          return if values.blank?
+
+          definition = infer_definition(values)
+          return if definition.blank?
+
+          ActionSpec::Schema.from_definition(definition)
+        end
+
+        def infer_definition(values)
+          values = Array(values)
+          present_values = values.compact
+          return if present_values.empty?
+
+          return infer_object_definition(present_values) if present_values.all? { |value| value.is_a?(Hash) }
+          return infer_array_definition(present_values) if present_values.all? { |value| value.is_a?(Array) }
+
+          infer_scalar_definition(present_values)
+        end
+
+        def infer_object_definition(values)
+          keys = values.flat_map(&:keys).map(&:to_s).uniq
+          keys.each_with_object(ActiveSupport::OrderedHash.new) do |key, definition|
+            child_values = values.select { |value| value.key?(key) || value.key?(key.to_sym) }.map { |value| value[key] || value[key.to_sym] }
+            child_definition = infer_definition(child_values)
+            next if child_definition.blank?
+
+            name = values.all? { |value| value.key?(key) || value.key?(key.to_sym) } ? :"#{key}!" : key.to_sym
+            definition[name] = child_definition
+          end
+        end
+
+        def infer_array_definition(values)
+          flattened = values.flatten(1)
+          item_definition = infer_definition(flattened)
+          item_definition ? [item_definition] : []
+        end
+
+        def infer_scalar_definition(values)
+          return Integer if values.all? { |value| value.is_a?(Integer) }
+          return Float if values.all? { |value| value.is_a?(Numeric) }
+          return :boolean if values.all? { |value| value == true || value == false }
+          return String if values.all? { |value| value.is_a?(String) }
+
+          String
+        end
     end
   end
 end

data/lib/action_spec/railtie.rb

@@ -1,5 +1,9 @@
 module ActionSpec
   class Railtie < ::Rails::Railtie
+    rake_tasks do
+      load File.expand_path("../tasks/action_spec_tasks.rake", __dir__)
+    end
+
     initializer "action_spec.controller" do
       ActiveSupport.on_load(:action_controller_base) do
         include ActionSpec::Doc

data/lib/action_spec/schema/array_of.rb

@@ -24,7 +24,7 @@ module ActionSpec
       end
 
       def copy
-        self.class.new(item.copy, default:, enum:, range:, pattern:, length:, allow_nil:, allow_blank:, desc: description, example:, examples:)
+        self.class.new(item.copy, default:, enum:, range:, pattern:, length:, blank:, desc: description, example:, examples:)
       end
     end
   end

data/lib/action_spec/schema/base.rb

@@ -3,7 +3,7 @@
 module ActionSpec
   module Schema
     class Base
-      attr_reader :default, :enum, :range, :pattern, :length, :allow_nil, :allow_blank, :description, :example, :examples
+      attr_reader :default, :enum, :range, :pattern, :length, :blank, :description, :example, :examples
 
       def initialize(options = {})
         options = options.symbolize_keys
@@ -12,17 +12,22 @@ module ActionSpec
         @range = options[:range]
         @pattern = options[:pattern]
         @length = options[:length]
-        @allow_nil = options[:allow_nil]
-        @allow_blank = options[:allow_blank]
+        @blank = options.key?(:blank) ? options[:blank] : options.fetch(:allow_blank, true)
         @description = options[:desc] || options[:description]
         @example = options[:example]
         @examples = options[:examples]
       end
 
-      def materialize_missing(_context:, _coerce:, _result:, _path:)
+      alias allow_blank blank
+
+      def materialize_missing(context:, coerce:, result:, path:)
         Schema::Missing
       end
 
+      def blank_allowed?
+        blank != false
+      end
+
       def validate_constraints(value, result:, path:)
         return if value.nil?
 

data/lib/action_spec/schema/field.rb

@@ -3,12 +3,14 @@
 module ActionSpec
   module Schema
     class Field
-      attr_reader :name, :schema, :scopes
+      attr_reader :name, :schema, :transform, :px_key, :scopes
 
-      def initialize(name:, required:, schema:, scopes: [])
+      def initialize(name:, required:, schema:, transform: nil, px_key: nil, scopes: [])
         @name = name.to_sym
         @required = required
         @schema = schema
+        @transform = transform
+        @px_key = px_key&.to_sym
         @scopes = Array(scopes).map(&:to_sym).freeze
       end
 
@@ -20,9 +22,48 @@ module ActionSpec
         schema.default
       end
 
+      def output_name
+        px_key || name
+      end
+
+      def transform_value(value, context: nil)
+        return value if transform.nil? || value.equal?(ActionSpec::Schema::Missing)
+
+        case transform
+        when Symbol, String then apply_symbol_transform(value, context:)
+        when Proc then apply_proc_transform(value, context:)
+        else value
+        end
+      end
+
       def copy
-        self.class.new(name:, required: required?, schema: schema.copy, scopes:)
+        self.class.new(name:, required: required?, schema: schema.copy, transform:, px_key:, scopes:)
       end
+
+      private
+
+        def apply_symbol_transform(value, context:)
+          symbol = transform.to_sym
+          return value.public_send(symbol) if value.respond_to?(symbol)
+          return invoke_context_transform(context, symbol, value) if context&.respond_to?(symbol, true)
+
+          value
+        end
+
+        def apply_proc_transform(value, context:)
+          return context.instance_exec(&transform) if context && transform.arity.zero?
+          return context.instance_exec(value, &transform) if context && (transform.arity == 1 || transform.arity.negative?)
+          return transform.call if transform.arity.zero?
+
+          transform.call(value)
+        end
+
+        def invoke_context_transform(context, symbol, value)
+          method = context.method(symbol)
+          return context.public_send(symbol) if method.arity.zero?
+
+          context.public_send(symbol, value)
+        end
     end
   end
 end

data/lib/action_spec/schema/object_of.rb

@@ -24,7 +24,7 @@ module ActionSpec
             result:,
             path:
           ).resolve
-          output[field.name] = resolved unless resolved.equal?(Schema::Missing)
+          output[field.output_name] = resolved unless resolved.equal?(Schema::Missing)
         end
         output.presence || (source.present? ? output : Schema::Missing)
       end
@@ -34,7 +34,7 @@ module ActionSpec
       end
 
       def copy
-        self.class.new(fields.transform_values(&:copy), default:, enum:, range:, pattern:, length:, allow_nil:, allow_blank:, desc: description, example:, examples:)
+        self.class.new(fields.transform_values(&:copy), default:, enum:, range:, pattern:, length:, blank:, desc: description, example:, examples:)
       end
 
       private

data/lib/action_spec/schema/resolver.rb

@@ -15,7 +15,10 @@ module ActionSpec
       def resolve
         return resolve_missing unless present?
 
-        schema.cast(value, context:, coerce:, result:, path:)
+        return resolve_nil if value.nil?
+        return resolve_blank if blank_disallowed?
+
+        finalize(schema.cast(value, context:, coerce:, result:, path:))
       end
 
       private
@@ -36,15 +39,35 @@ module ActionSpec
 
         def resolve_missing
           if schema.default.respond_to?(:call)
-            return schema.cast(evaluate_default(schema.default), context:, coerce:, result:, path:)
+            return finalize(schema.cast(evaluate_default(schema.default), context:, coerce:, result:, path:))
           end
-          return schema.cast(schema.default, context:, coerce:, result:, path:) unless schema.default.nil?
-          return schema.materialize_missing(context:, coerce:, result:, path:) unless field.required?
+          return finalize(schema.cast(schema.default, context:, coerce:, result:, path:)) unless schema.default.nil?
+          return finalize(schema.materialize_missing(context:, coerce:, result:, path:)) unless field.required?
 
           result.add_error(path.join("."), :required)
           Schema::Missing
         end
 
+        def resolve_nil
+          result.add_error(path.join("."), field.required? ? :required : :blank)
+          Schema::Missing
+        end
+
+        def resolve_blank
+          result.add_error(path.join("."), :blank)
+          Schema::Missing
+        end
+
+        def blank_disallowed?
+          !schema.blank_allowed? && value.respond_to?(:blank?) && value.blank?
+        end
+
+        def finalize(resolved)
+          return resolved if resolved.equal?(Schema::Missing)
+
+          field.transform_value(resolved, context:)
+        end
+
         def evaluate_default(default_proc)
           return context.instance_exec(&default_proc) if context && default_proc.arity.zero?
           return default_proc.call(context) if context && default_proc.arity == 1

data/lib/action_spec/schema/scalar.rb

@@ -14,7 +14,7 @@ module ActionSpec
         candidate = TypeCaster.cast(type, value)
       rescue TypeCaster::CastError => error
         result.add_error(path.join("."), :invalid_type, expected: error.expected)
-        nil
+        Schema::Missing
       else
         return candidate if candidate.nil?
 
@@ -23,7 +23,7 @@ module ActionSpec
       end
 
       def copy
-        self.class.new(type, default:, enum:, range:, pattern:, length:, allow_nil:, allow_blank:, desc: description, example:, examples:)
+        self.class.new(type, default:, enum:, range:, pattern:, length:, blank:, desc: description, example:, examples:)
       end
     end
   end

data/lib/action_spec/schema/type_caster.rb

@@ -25,7 +25,7 @@ module ActionSpec
           return cast_decimal(value) if normalized == :decimal
 
           active_model_type_for(normalized).cast(value).tap do |casted|
-            raise CastError, normalized if casted.nil? && value.present?
+            raise CastError, normalized if casted.nil? && !value.nil?
           end
         end
 

data/lib/action_spec/schema.rb

@@ -12,7 +12,8 @@ require "action_spec/schema/type_caster"
 module ActionSpec
   module Schema
     Missing = Object.new.freeze
-    OPTION_KEYS = %i[default desc enum range pattern length allow_nil allow_blank example examples].freeze
+    OPTION_KEYS = %i[default desc enum range pattern length blank allow_blank example examples].freeze
+    FIELD_OPTION_KEYS = (OPTION_KEYS + %i[required transform px px_key]).freeze
 
     class << self
       def build(type = nil, **options)
@@ -21,6 +22,17 @@ module ActionSpec
         from_definition(definition)
       end
 
+      def build_field(name, definition = nil, required: false, scopes: [])
+        Field.new(
+          name: field_name(name),
+          required: required_key?(name) || required || explicit_required?(definition),
+          schema: build_field_schema(strip_field_options(definition)),
+          transform: explicit_transform(definition),
+          px_key: explicit_px_key(definition),
+          scopes:
+        )
+      end
+
       def from_definition(definition)
         return Scalar.new(String) if definition.blank?
         return ArrayOf.new(from_definition(type: definition.first)) if definition.is_a?(Array) && definition.one?
@@ -42,13 +54,8 @@ module ActionSpec
 
       def build_fields(definition_hash, scopes: [])
         definition_hash.each_with_object(ActiveSupport::OrderedHash.new) do |(name, definition), fields|
-          schema = build_field_schema(definition)
-          fields[field_name(name)] = Field.new(
-            name: field_name(name),
-            required: required_key?(name),
-            schema:,
-            scopes:
-          )
+          field = build_field(name, definition, scopes:)
+          fields[field.name] = field
         end
       end
 
@@ -64,11 +71,61 @@ module ActionSpec
         return from_definition(type: definition) unless definition.is_a?(Hash)
 
         definition = definition.symbolize_keys
-        return from_definition(definition) if definition.key?(:type)
-        return from_definition(definition) if (definition.keys - OPTION_KEYS).present?
+        return from_definition(definition.except(:required)) if definition.key?(:type)
+        return from_definition(definition.except(:required)) if (definition.keys - FIELD_OPTION_KEYS).present?
+
+        from_definition(definition.except(:required).merge(type: String))
+      end
+
+      def schema_definition?(definition)
+        case definition
+        when Array
+          definition.one? && schema_definition?(definition.first)
+        when Hash
+          definition = definition.with_indifferent_access
+          return true if definition.key?(:type)
+          return true if definition.keys.all? { |key| FIELD_OPTION_KEYS.include?(key.to_sym) }
 
-        from_definition(definition.merge(type: String))
+          definition.any? do |name, value|
+            required_key?(name) || schema_definition?(value)
+          end
+        when Class
+          true
+        when Symbol
+          definition == :boolean || definition == :file || definition == :object
+        else
+          false
+        end
       end
+
+      private
+
+        def explicit_required?(definition)
+          definition.is_a?(Hash) && definition.symbolize_keys[:required] == true
+        end
+
+        def explicit_transform(definition)
+          definition.is_a?(Hash) ? definition.symbolize_keys[:transform] : nil
+        end
+
+        def explicit_px_key(definition)
+          return unless definition.is_a?(Hash)
+
+          options = definition.symbolize_keys
+          normalize_px_key(options[:px_key] || options[:px])
+        end
+
+        def normalize_px_key(value)
+          return if value.nil? || value == true || value == false
+
+          value.is_a?(String) || value.is_a?(Symbol) ? value.to_sym : value
+        end
+
+        def strip_field_options(definition)
+          return definition unless definition.is_a?(Hash)
+
+          definition.symbolize_keys.except(:required, :transform, :px, :px_key)
+        end
     end
   end
 end