action_spec 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 432c84ac7303d7194f5617f2fe724bdb2d332662eb543a0545712731cac767dc
-  data.tar.gz: 90343cbda95d9a89452aabf86da6731606d2404a4c2bcd0a9358b48f705bd6cb
+  metadata.gz: 9218555ca7d33709a7a5b22528f6900358e36247c123e521f2342d7a36ac02b5
+  data.tar.gz: e771af58669e707ccbcc922b6d9afa726a2b25817ab4836e01ce1154bd22344b
 SHA512:
-  metadata.gz: 631a11eea99a092b2c104ff3934fcddd1777f8a2346468ef91170ff1bc5acea9844002b438b4ec668a5a20f7a97d58c69bdf8f99482b1b757e4ccf01fadf119c
-  data.tar.gz: 886a2975a48967efcf844c4577f05c2ebbb4cd8ed2d6c883e80c6830b1388f57b38b9f6e202376b01a71d1109ec75869d20ab143950d60cb5638e98e4b111c02
+  metadata.gz: 7d03ee8f19de7c1c874302344eadf224f9aa3fba2dab228f2f4b44448a2865ba53dd97385587b6b9691308e4a987048b1eab6e5f55a1b03ef93424a643857a0c
+  data.tar.gz: 357fe37dc9a591740079c76dd3e4238a9485cb0d1e57ab020bed09bf737d1937ef22b777f8b062f78473fe497965c2df754ee3858a97f77bdd59674002cdda69

data/README.md

@@ -16,7 +16,7 @@ Concise and Powerful API Documentation Solution for Rails. [中文](README_zh.md
    2. [`doc_dry`](#doc_dry)
    3. [DSL Inside `doc`](#dsl-inside-doc)
       1. [Parameter](#parameter)
-      2. [request body](#request-body)
+      2. [Request body](#request-body)
       3. [`openapi false`](#openapi-false)
       4. [Scope](#scope)
       5. [Response](#response)
@@ -29,7 +29,8 @@ Concise and Powerful API Documentation Solution for Rails. [中文](README_zh.md
 4. [Parameter Validation And Type Coercion](#parameter-validation-and-type-coercion)
    1. [Validation Flow](#validation-flow)
    2. [Reading Processed Values With `px`](#reading-processed-values-with-px)
-   3. [Errors](#errors)
+   3. [`px` is Whitelist Extraction](#px-is-whitelist-extraction)
+   4. [Errors](#errors)
 5. [Configuration And I18n](#configuration-and-i18n)
    1. [Configuration](#configuration)
    2. [I18n](#i18n)
@@ -44,25 +45,26 @@ class UsersController < ApplicationController
   doc {
     header :Authorization, String
     path :account_id, Integer
-    query :locale, String, default: "zh-CN"
-    query :page, Integer, default: -> { 1 }
+    query :locale, String, default: "zh-CN", transform: -> { it.downcase }
+    query :key_number, Integer, default: -> { it + 1 }, px: :key
 
     form data: {
-      name!: String,
-      age: Integer,
+      name!: { type: String, transform: :strip },
       birthday: Date,
       admin: { type: :boolean, default: false },
-      tags: [String],
-      profile: {
-        nickname!: String
-      }
+      tags: [{ id: Integer, content!: { type: String, blank: false } }],
+      profile: { nickname!: String }
     }
 
-    response 200, desc: "success"
+    response 200, "success", :json, data: { code: Integer, result: [Hash] }
+    errors 400, "client errors", {
+      invalid_params: { code: 1234, message: "parameters are invalid" },
+      missing_params: { code: 1235, message: "parameters are missing" }
+    }
   }
   def create
-    User.create!(
-      account_id: px[:account_id], name: px[:name],
+    User.find(px[:account_id]).update!(
+      key: px[:key], name: px[:name],
       **px.slice(:birthday, :admin, :profile)
     )
   end
@@ -235,7 +237,7 @@ in_query!(
 )
 ```
 
-#### request body 
+#### Request body
 
 General form:
 
@@ -296,7 +298,28 @@ Then read it from `px.scope`:
 px.scope[:user] # => { user_id: 1, name: "Tom" }
 ```
 
-#### Response 
+You can also trim custom scope buckets with `compact:` or `compact_blank:`:
+
+```ruby
+doc {
+  scope(:search, compact: true) {
+    query :page, Integer, transform: -> { nil }, px: :page_number
+    query :keyword, String
+  }
+
+  scope(:filters, compact_blank: true) {
+    query :q, String, transform: :strip
+    query :nickname, String, transform: -> { "" }
+  }
+}
+
+px.scope[:search]  # => { keyword: "rails" }
+px.scope[:filters] # => { q: "ruby" }
+```
+
+These options only apply to the custom `px.scope[:name]` bucket defined by that `scope`, and use shallow hash compaction.
+
+#### Response
 
 ```ruby
 response 200, desc: "success"
@@ -363,21 +386,37 @@ Scalar types currently supported by validation/coercion:
 - `DateTime`
 - `Time`
 - `File`
-- `Object`
+- `Object` / `Hash`
 
-Nested forms:
+```ruby
+query :page, Integer
+form data: { file: File }
+```
+
+Object and Nested Object forms:
 
 ```ruby
 json data: {
-  tags: [String],
-  profile: {
-    nickname!: String
-  },
-  settings: { type: Object },
-  users: [{ id: Integer }]
+  settings: Object,
+  # == settings: { type: Object }
+  # == settings: { type: Hash }
+  # == settings: { type: { } }
+
+  profile: { nickname!: String },
+  tags: [],
+  # == tags: { type: [] }
+  foo: [{ id: Integer }],
+
+  users: {
+    type: { name!: String },
+    default: { name: "Tom" },
+    transform: -> { { name: it[:name].downcase } }
+  }
 }
 ```
 
+When you write `xx: { type: ... }`, the type of `xx` comes from `type`. In other words, `type` is a reserved schema keyword here, not a normal nested field name.
+
 #### Field Options
 
 ```ruby
@@ -391,12 +430,35 @@ query :title, String, blank: false # or allow_blank: false
 query :nickname, String, transform: :downcase
 query :page, Integer, transform: -> { it + 1 }, px: :page_number
 query :request_id, String, px_key: :trace_id
+query :end_at, Integer, validate: -> { it >= px[:start_at] }
 ```
 
 Notes:
 
 - `transform` accepts a `Symbol` or a `Proc` and runs **after coercion**, before the value is written into `px`
 - `px` and `px_key` customize the key name written into `px`; `px` is the short form of `px_key`
+- `validate` accepts a `Proc` and runs **after all parameters have been resolved, coerced, transformed, and written into `px`**
+- `validate` runs in the current controller context, so it can read `px` and call methods such as `current_user`
+- when `validate` returns `false` or `nil`, the field adds an `invalid` error
+
+About nested object fields
+
+Inner field options run first, and the outer object field runs last.  
+In other words, nested `transform` / `px` first participate in building the object, and after the whole object has been built, the outer field receives that final object and continues processing it.  
+Only after the whole object tree has finished resolving, coercing, and transforming does ActionSpec enter the post-`validate` phase: inner field `validate` callbacks run first, and outer object field `validate` callbacks run afterwards.
+
+```ruby
+json data: {
+  user: {
+    type: {
+      name: { type: String, transform: :strip, px: :nickname }
+    },
+    transform: -> { { name: it[:nickname].downcase } }
+  }
+}
+
+px[:user] # => { "name" => "tom" }
+```
 
 These options are used by OpenAPI generation:
 
@@ -434,10 +496,16 @@ You can also limit the exported fields:
 User.schemas(only: %i[name phone role])
 ```
 
+`bang:` defaults to `true`, so required fields are emitted as bang keys such as `"name!"`. If you prefer plain keys, you can pass `bang: false`, and required fields will be emitted as `required: true` instead:
+
+```ruby
+User.schemas(bang: false)
+```
+
 ActionSpec extracts schema-relevant information from ActiveRecord / ActiveModel when available, including:
 
 - field type
-- requiredness, rendered as bang keys such as `"name!"`
+- requiredness, rendered either as bang keys such as `"name!"` or as `required: true` when `bang: false`
 - enum values from `enum`
 - `default`
 - `desc` from column comments
@@ -454,6 +522,13 @@ User.schemas
 #   "phone!" => { type: String, length: { maximum: 13 }, pattern: /\A1\d{10}\z/ },
 #   "role" => { type: String, enum: %w[admin member visitor] }
 # }
+
+User.schemas(bang: false)
+# {
+#   "name" => { type: String, required: true, desc: "user name", length: { maximum: 20 } },
+#   "phone" => { type: String, required: true, length: { maximum: 13 }, pattern: /\A1\d{10}\z/ },
+#   "role" => { type: String, enum: %w[admin member visitor] }
+# }
 ```
 
 #### Type And Boundary Matrix
@@ -532,12 +607,13 @@ px.scope[:query]
 px.scope[:body]
 px.scope[:headers]
 px.scope[:cookies]
+px.scope[:the_scope_you_defined]
 ```
 
 Notes:
 
 - every declared field from path/query/body is also flattened into the top-level `px[:field]`
-- custom `scope(:name)` buckets are also exposed through `px.scope[:name]`
+- `px` itself is an `ActiveSupport::HashWithIndifferentAccess`, and nested object values such as `px[:profile]` are also returned as indifferent hashes
 - headers and cookies stay inside their own grouped buckets; for example, `px[:Authorization]` is not a top-level shortcut
 - header keys are stored in lowercase dashed form, but reading remains compatible with original forms such as `Authorization` and `HTTP_AUTHORIZATION`, for example:
 
@@ -549,6 +625,28 @@ px.scope[:headers]["HTTP_AUTHORIZATION"]
 
 - original `params` are not mutated
 
+### `px` is Whitelist Extraction
+
+```ruby
+json data: {
+  profile: {
+    nickname: String
+  }
+}
+
+# request params
+{
+  profile: {
+    nickname: "Neo",
+    role: "admin"
+  }
+}
+
+px[:profile] # => { "nickname" => "Neo" }
+```
+
+Undeclared fields are filtered out, including extra keys inside nested objects.
+
 ### Errors
 
 Validation errors are stored in `ActiveModel::Errors`.
@@ -640,6 +738,7 @@ When using AI tools to generate Rails controller code, and the change involves p
 - when a batch has 3 fields or fewer and does not contain nested hashes, prefer a single-line style, for example:
   - `json data: { type: String, required: true }`
   - `in_query(name: String, value: String)` (prefer `in_xxx(...)` batch declarations over multiple `xx` DSL lines when possible)
+- use `!` but not `required: true`
 - use `doc_dry`, `scope`, and `transform`、`px(px_key)`、`px.slice` to keep controller concise
 - when request parameters match model declarations, prefer `.schemas` to keep `doc` concise
 

data/lib/action_spec/doc/dsl.rb

@@ -56,7 +56,8 @@ module ActionSpec
         add_body(:form, { name => options.merge(type:) })
       end
 
-      def scope(name, &block)
+      def scope(name, compact: nil, compact_blank: nil, &block)
+        endpoint.request.register_scope(name, compact:, compact_blank:)
         scopes.push(name.to_sym)
         instance_exec(&block)
       ensure

data/lib/action_spec/doc/endpoint.rb

@@ -38,7 +38,7 @@ module ActionSpec
     end
 
     class Request
-      attr_reader :header, :path, :query, :cookie, :body, :body_media_types
+      attr_reader :header, :path, :query, :cookie, :body, :body_media_types, :scope_options
 
       def initialize
         @header = Location.new(:header)
@@ -47,6 +47,7 @@ module ActionSpec
         @cookie = Location.new(:cookie)
         @body = Location.new(:body)
         @body_media_types = {}
+        @scope_options = ActiveSupport::HashWithIndifferentAccess.new
         @body_required = false
       end
 
@@ -63,6 +64,16 @@ module ActionSpec
         (@body_media_types[media_type.to_sym] ||= Location.new(media_type.to_sym)).add(field.copy)
       end
 
+      def register_scope(name, compact: nil, compact_blank: nil)
+        key = name.to_sym
+        @scope_options[key] = scope_options.fetch(key, {}).merge(
+          {
+            compact:,
+            compact_blank:
+          }.compact
+        )
+      end
+
       def require_body!
         @body_required = true
       end
@@ -78,6 +89,7 @@ module ActionSpec
         @cookie = other.cookie
         @body = other.body
         @body_media_types = other.body_media_types
+        @scope_options = other.scope_options
         @body_required = other.body_required?
       end
 
@@ -92,9 +104,14 @@ module ActionSpec
             :@body_media_types,
             body_media_types.transform_values(&:copy)
           )
+          request.instance_variable_set(:@scope_options, scope_options.deep_dup)
           request.instance_variable_set(:@body_required, body_required?)
         end
       end
+
+      def custom_validation?
+        [header, path, query, cookie, body].any?(&:custom_validation?)
+      end
     end
 
     class Location
@@ -132,6 +149,10 @@ module ActionSpec
           fields.each { |field| location.add(field.copy) }
         end
       end
+
+      def custom_validation?
+        fields.any?(&:custom_validation?)
+      end
     end
 
     class Response

data/lib/action_spec/schema/active_record.rb

@@ -6,12 +6,12 @@ module ActionSpec
       extend ActiveSupport::Concern
 
       class_methods do
-        def schemas(only: nil)
+        def schemas(only: nil, bang: true)
           names = selected_column_names(only)
           @action_spec_validator_index = build_validator_index
 
           names.each_with_object(ActiveSupport::OrderedHash.new) do |name, hash|
-            hash[output_name(name)] = schema_definition_for(name)
+            hash[output_name(name, bang:)] = schema_definition_for(name, bang:)
           end
         ensure
           remove_instance_variable(:@action_spec_validator_index) if instance_variable_defined?(:@action_spec_validator_index)
@@ -25,12 +25,13 @@ module ActionSpec
             column_names.select { |name| selected.include?(name) }
           end
 
-          def output_name(name)
-            required_attribute?(name) ? "#{name}!" : name
+          def output_name(name, bang:)
+            bang && required_attribute?(name) ? "#{name}!" : name
           end
 
-          def schema_definition_for(name)
+          def schema_definition_for(name, bang:)
             definition = { type: schema_type_for(name) }
+            definition[:required] = true if required_attribute?(name) && !bang
             definition[:default] = column_default_for(name) unless column_default_for(name).nil?
             definition[:desc] = column_comment_for(name) if column_comment_for(name).present?
             definition[:enum] = resolved_enum_for(name) if resolved_enum_for(name).present?

data/lib/action_spec/schema/array_of.rb

@@ -26,6 +26,10 @@ module ActionSpec
       def copy
         self.class.new(item.copy, default:, enum:, range:, pattern:, length:, blank:, desc: description, example:, examples:)
       end
+
+      def custom_validation?
+        item.custom_validation?
+      end
     end
   end
 end

data/lib/action_spec/schema/base.rb

@@ -40,6 +40,10 @@ module ActionSpec
         raise NotImplementedError
       end
 
+      def custom_validation?
+        false
+      end
+
       private
 
         def add_error(result, path, type, **options)

data/lib/action_spec/schema/field.rb

@@ -3,13 +3,14 @@
 module ActionSpec
   module Schema
     class Field
-      attr_reader :name, :schema, :transform, :px_key, :scopes
+      attr_reader :name, :schema, :transform, :validate, :px_key, :scopes
 
-      def initialize(name:, required:, schema:, transform: nil, px_key: nil, scopes: [])
+      def initialize(name:, required:, schema:, transform: nil, validate: nil, px_key: nil, scopes: [])
         @name = name.to_sym
         @required = required
         @schema = schema
         @transform = transform
+        @validate = validate
         @px_key = px_key&.to_sym
         @scopes = Array(scopes).map(&:to_sym).freeze
       end
@@ -36,8 +37,21 @@ module ActionSpec
         end
       end
 
+      def validate_value(value, context: nil)
+        return true if validate.nil? || value.equal?(ActionSpec::Schema::Missing)
+
+        case validate
+        when Proc then apply_validation_proc(value, context:)
+        else true
+        end
+      end
+
+      def custom_validation?
+        validate.present? || schema.custom_validation?
+      end
+
       def copy
-        self.class.new(name:, required: required?, schema: schema.copy, transform:, px_key:, scopes:)
+        self.class.new(name:, required: required?, schema: schema.copy, transform:, validate:, px_key:, scopes:)
       end
 
       private
@@ -58,6 +72,14 @@ module ActionSpec
           transform.call(value)
         end
 
+        def apply_validation_proc(value, context:)
+          return context.instance_exec(&validate) if context && validate.arity.zero?
+          return context.instance_exec(value, &validate) if context && (validate.arity == 1 || validate.arity.negative?)
+          return validate.call if validate.arity.zero?
+
+          validate.call(value)
+        end
+
         def invoke_context_transform(context, symbol, value)
           method = context.method(symbol)
           return context.public_send(symbol) if method.arity.zero?

data/lib/action_spec/schema/object_of.rb

@@ -37,6 +37,10 @@ module ActionSpec
         self.class.new(fields.transform_values(&:copy), default:, enum:, range:, pattern:, length:, blank:, desc: description, example:, examples:)
       end
 
+      def custom_validation?
+        fields.any? { |_name, field| field.custom_validation? }
+      end
+
       private
 
         def normalize_source(value, result:, path:)

data/lib/action_spec/schema.rb

@@ -13,7 +13,7 @@ module ActionSpec
   module Schema
     Missing = Object.new.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
+    FIELD_OPTION_KEYS = (OPTION_KEYS + %i[required transform px px_key validate]).freeze
 
     class << self
       def build(type = nil, **options)
@@ -28,6 +28,7 @@ module ActionSpec
           required: required_key?(name) || required || explicit_required?(definition),
           schema: build_field_schema(strip_field_options(definition)),
           transform: explicit_transform(definition),
+          validate: explicit_validate(definition),
           px_key: explicit_px_key(definition),
           scopes:
         )
@@ -42,9 +43,17 @@ module ActionSpec
         definition = definition.deep_symbolize_keys
         if definition.key?(:type)
           type = definition[:type]
-          options = definition.except(:type)
+          options = definition.slice(*OPTION_KEYS)
           return ArrayOf.new(from_definition(type: type.first), options) if type.is_a?(Array) && type.one?
-          return ObjectOf.new(build_fields(definition.except(:type, *OPTION_KEYS))) if type == Object && definition.except(:type, *OPTION_KEYS).present?
+          return ArrayOf.new(from_definition(type: nil), options) if type == []
+          if type.is_a?(Hash)
+            return Scalar.new(Object, options) if type.empty?
+
+            return ObjectOf.new(build_fields(type), options)
+          end
+          if [Object, Hash].include?(type) && definition.except(:type, *OPTION_KEYS).present?
+            return ObjectOf.new(build_fields(definition.except(:type, *OPTION_KEYS)), options)
+          end
 
           return Scalar.new(type, options)
         end
@@ -108,6 +117,10 @@ module ActionSpec
           definition.is_a?(Hash) ? definition.symbolize_keys[:transform] : nil
         end
 
+        def explicit_validate(definition)
+          definition.is_a?(Hash) ? definition.symbolize_keys[:validate] : nil
+        end
+
         def explicit_px_key(definition)
           return unless definition.is_a?(Hash)
 
@@ -124,7 +137,7 @@ module ActionSpec
         def strip_field_options(definition)
           return definition unless definition.is_a?(Hash)
 
-          definition.symbolize_keys.except(:required, :transform, :px, :px_key)
+          definition.symbolize_keys.except(:required, :transform, :px, :px_key, :validate)
         end
     end
   end

data/lib/action_spec/validation_result.rb

@@ -30,6 +30,16 @@ module ActionSpec
       Array(scopes).each { |scope_name| scope_bucket(scope_name)[key] = value }
     end
 
+    def apply_scope_options!(options_by_scope)
+      options_by_scope.each do |scope_name, options|
+        bucket = px.scope[scope_name]
+        next unless bucket
+
+        bucket.compact! if options[:compact]
+        bucket.delete_if { |_key, value| value.blank? } if options[:compact_blank]
+      end
+    end
+
     def add_error(attribute, type, **options)
       if (message = ActionSpec.config.message_for(attribute, type, options))
         errors.add(attribute, message)

data/lib/action_spec/validator/runner.rb

@@ -16,6 +16,8 @@ module ActionSpec
         merge_body!(result)
         merge_group!(result, endpoint.request.header, source: header_source, location: :headers)
         merge_group!(result, endpoint.request.cookie, source: cookie_source, location: :cookies)
+        result.apply_scope_options!(endpoint.request.scope_options)
+        apply_custom_validations!(result)
         result
       end
 
@@ -23,6 +25,14 @@ module ActionSpec
 
         attr_reader :endpoint, :controller, :coerce
 
+        BUILT_IN_GROUPS = {
+          path: ->(request) { request.path },
+          query: ->(request) { request.query },
+          body: ->(request) { request.body },
+          headers: ->(request) { request.header },
+          cookies: ->(request) { request.cookie }
+        }.freeze
+
         def merge_body!(result)
           if endpoint.request.body_required? && body_source.blank?
             result.add_error("body", :required)
@@ -90,6 +100,100 @@ module ActionSpec
 
           field.name
         end
+
+      def apply_custom_validations!(result)
+        return unless endpoint.request.custom_validation?
+
+        with_controller_px(result.px) do
+          BUILT_IN_GROUPS.each do |location, group_reader|
+            validate_group!(
+                result,
+                group_reader.call(endpoint.request),
+                values: result.px.scope.fetch(location),
+                location:
+              )
+            end
+          end
+        end
+
+        def validate_group!(result, group, values:, location:)
+          return unless group.custom_validation?
+
+          group.fields.each do |field|
+            next unless field.custom_validation?
+
+            key = storage_key(field, location)
+            next unless values.key?(key)
+
+            validate_field!(field, values[key], result:, path: [field.name])
+          end
+        end
+
+        def validate_field!(field, value, result:, path:)
+          validate_nested_schema!(field.schema, value, result:, path:)
+          return if field.validate_value(value, context: controller)
+
+          result.add_error(path.join("."), :invalid)
+        end
+
+        def validate_nested_schema!(schema, value, result:, path:)
+          return unless schema.custom_validation?
+
+          case schema
+          when ActionSpec::Schema::ObjectOf
+            return unless value.is_a?(Hash)
+
+            source = value.with_indifferent_access
+            schema.fields.each_value do |field|
+              next unless field.custom_validation?
+              next unless source.key?(field.output_name)
+
+              validate_field!(field, source[field.output_name], result:, path: [*path, field.name])
+            end
+          when ActionSpec::Schema::ArrayOf
+            return unless value.is_a?(Array)
+
+            value.each_with_index do |entry, index|
+              validate_array_item!(schema.item, entry, result:, path: [*path, index])
+            end
+          end
+        end
+
+        def validate_array_item!(schema, value, result:, path:)
+          return unless schema.custom_validation?
+
+          case schema
+          when ActionSpec::Schema::ObjectOf
+            return unless value.is_a?(Hash)
+
+            source = value.with_indifferent_access
+            schema.fields.each_value do |field|
+              next unless field.custom_validation?
+              next unless source.key?(field.output_name)
+
+              validate_field!(field, source[field.output_name], result:, path: [*path, field.name])
+            end
+          when ActionSpec::Schema::ArrayOf
+            return unless value.is_a?(Array)
+
+            value.each_with_index do |entry, index|
+              validate_array_item!(schema.item, entry, result:, path: [*path, index])
+            end
+          end
+        end
+
+        def with_controller_px(px)
+          previous_defined = controller.instance_variable_defined?(:@px)
+          previous = controller.instance_variable_get(:@px)
+          controller.instance_variable_set(:@px, px)
+          yield
+        ensure
+          if previous_defined
+            controller.instance_variable_set(:@px, previous)
+          else
+            controller.remove_instance_variable(:@px) if controller.instance_variable_defined?(:@px)
+          end
+        end
     end
   end
 end

data/lib/action_spec/version.rb

@@ -1,3 +1,3 @@
 module ActionSpec
-  VERSION = "1.4.0"
+  VERSION = "1.5.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: action_spec
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.5.0
 platform: ruby
 authors:
 - zhandao