action_spec 1.4.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 432c84ac7303d7194f5617f2fe724bdb2d332662eb543a0545712731cac767dc
-  data.tar.gz: 90343cbda95d9a89452aabf86da6731606d2404a4c2bcd0a9358b48f705bd6cb
+  metadata.gz: d4483d08f3dbf8917159d539ee9b064366551409ae646714def0b89595484428
+  data.tar.gz: 065af0d1f835124179afef0a756515b6184598cd35ef217a96615f18b2098cbe
 SHA512:
-  metadata.gz: 631a11eea99a092b2c104ff3934fcddd1777f8a2346468ef91170ff1bc5acea9844002b438b4ec668a5a20f7a97d58c69bdf8f99482b1b757e4ccf01fadf119c
-  data.tar.gz: 886a2975a48967efcf844c4577f05c2ebbb4cd8ed2d6c883e80c6830b1388f57b38b9f6e202376b01a71d1109ec75869d20ab143950d60cb5638e98e4b111c02
+  metadata.gz: 71ae3fd218312cb0e788f7a5affad8e31da416546e319852509d260490fe261009be24fc51cedfc5948c8c7e9cee04285b50019e613316f3a96605d7cee98b1f
+  data.tar.gz: 7aaee031ed042a3631c952789ccf4ca37db7f7a7f53fcb6a45f1a0e8c4badad005cd4e8774fad58d467c8b2f49d543f4d499407b98cad4dde8fe4e6dbe7cc197

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
@@ -199,6 +201,16 @@ cookie! :remember_token, String
 
 Bang methods mark the field as required. For example, `query! :page, Integer` means the request must include `page`, and the value must not be `nil`. Blank values are still allowed unless you set `blank: false`.
 
+You can also change that default globally:
+
+```ruby
+ActionSpec.configure do |config|
+  config.required_allow_blank = false
+end
+```
+
+With `required_allow_blank = false`, required fields reject blank strings unless that field explicitly sets `blank:` or `allow_blank:`.
+
 If you prefer not to use bang methods, you can also write `required: true`:
 
 ```ruby
@@ -235,7 +247,7 @@ in_query!(
 )
 ```
 
-#### request body 
+#### Request body
 
 General form:
 
@@ -296,7 +308,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"
@@ -348,7 +381,9 @@ Meaning of `!`:
 
 You can also use `required: true` instead of bang syntax for parameters, nested fields, and the root request body.
 
-`required` in ActionSpec means "present and not `nil`". It does not reject blank strings by itself. If you want to reject blank values, use `blank: false` or `allow_blank: false`.
+`required` in ActionSpec means "present and not `nil`". By default it does not reject blank strings. You can keep that default, change it globally with `config.required_allow_blank`, or override it per field with `blank:` / `allow_blank:`.
+
+When blank values are allowed, type coercion does not fail just because the input is an empty string. If the field can still carry a meaningful blank value, such as `String`, the original blank string stays in `px`. Otherwise, ActionSpec stores `nil` for that field. For example, `""` stays `""` for `String`, but becomes `nil` for `Date`.
 
 #### Field Types
 
@@ -363,21 +398,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
@@ -386,17 +437,77 @@ query :today, Date, default: -> { Time.current.to_date }
 query :status, String, enum: %w[draft published]
 query :score, Integer, range: { ge: 1, le: 5 }
 query :slug, String, pattern: /\A[a-z\-]+\z/
-query :title, String, blank: false # or allow_blank: false
+query :title, String, 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: -> { current_user && it >= px[:start_at] }
+query :birthday, Date, error: "birthday error"
 ```
 
-Notes:
+- `required`
+  - Marks the field as required.
+  - Can replace bang syntax when you do not use `name!:`.
+- `default`
+  - Default value used when the field is missing.
+  - Can be a literal or `-> { }`.
+- `enum`
+  - Restricts the field to values from a fixed set.
+- `range`
+  - Numeric range constraints.
+  - Available: `ge` / `gt` / `le` / `lt`
+- `pattern`
+  - Regex constraint.
+- `length`
+  - Length constraints.
+  - Available: `minimum` / `maximum` / `is`
+- `blank` / `allow_blank`
+  - Controls whether blank values are allowed.
+  - For fields such as `Date`, if blank is allowed, no type coercion is applied and the value becomes `nil`.
+
+- `desc`
+  - Used only for OpenAPI description generation.
+- `example`
+  - Used only for generating a single OpenAPI example.
+- `examples`
+  - Used only for generating multiple OpenAPI examples.
+
+- `transform`
+  - Applies one more custom transformation to the **already-coerced value**.
+  - Accepts a `Symbol` or a `Proc`.
+- `px` / `px_key`
+  - Customize the key name used when the parameter is written into `px`.
+- `validate`
+  - Accepts a `Proc`.
+  - Runs **after all parameters have finished resolving, coercion, transform, and writing into `px`**.
+  - Runs in the current controller context, so it can read `px` and directly call controller methods such as `current_user`.
+  - When `validate` returns `false` or `nil`, the field adds an `invalid` error.
+- `error` / `error_message`
+  - Override the error message used when that field fails validation or coercion.
+  - Supported forms:
+    - `String`
+    - `-> { }`
+    - `->(error, value) { }`
+  - Field-level `error` / `error_message` have higher priority than global `config.error_messages`.
+
+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.
 
-- `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`
+```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:
 
@@ -420,7 +531,7 @@ class UsersController < ApplicationController
 end
 ```
 
-`User.schemas` returns a hash that can be passed directly into `form data:`, `json data:`, or `body`.
+`User.schemas` returns a symbol-keyed hash that can be passed directly into `form data:`, `json data:`, or `body`.
 
 By default, it includes all model fields:
 
@@ -434,10 +545,46 @@ You can also limit the exported fields:
 User.schemas(only: %i[name phone role])
 ```
 
+Or exclude specific fields:
+
+```ruby
+User.schemas(except: %i[phone role])
+```
+
+When `only:` and `except:` are used together, ActionSpec applies `except:` after `only:`.
+
+You can also extract validators for a specific validation context:
+
+```ruby
+User.schemas(on: :create)
+```
+
+You can also override requiredness in the exported schema:  
+When `required:` is an array, only the listed fields are treated as required, and every other exported field is treated as non-required.
+
+```ruby
+User.schemas(required: true)
+User.schemas(required: false)
+User.schemas(required: %i[name role])
+```
+
+You can also merge custom schema fragments into the exported fields:
+
+```ruby
+User.schemas(merge: { name: { required: false, desc: "nickname" } })
+```
+
+`bang:` defaults to `true`, so required fields are emitted as bang keys such as `name!:`. `only:` and `except:` both accept plain names or bang-style names such as `phone!`. 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`
+- `allow_blank: false` from presence validators unless that validator explicitly allows blank
 - enum values from `enum`
 - `default`
 - `desc` from column comments
@@ -445,15 +592,19 @@ ActionSpec extracts schema-relevant information from ActiveRecord / ActiveModel
 - `range` from numericality validators
 - `length` from length validators and string column limits
 
+Conditional validators with `if:` or `unless:` are skipped during schema extraction, because they cannot be represented as unconditional static schema rules. Validators with `on:` / `except_on:` are skipped by default, but can be extracted by passing `schemas(on: ...)`. The `required:` option overrides the requiredness of exported fields only; it does not remove other extracted constraints such as `allow_blank: false`. The `merge:` option deep-merges custom fragments into each extracted field definition.
+
 Example output:
 
 ```ruby
 User.schemas
 # {
-#   "name!" => { type: String, desc: "user name", length: { maximum: 20 } },
-#   "phone!" => { type: String, length: { maximum: 13 }, pattern: /\A1\d{10}\z/ },
-#   "role" => { type: String, enum: %w[admin member visitor] }
+#   name!: { type: String, desc: "user name", length: { maximum: 20 } },
+#   phone!: { type: String, allow_blank: false, 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 } }, ... }
 ```
 
 #### Type And Boundary Matrix
@@ -532,12 +683,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 +701,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`.
@@ -631,6 +805,18 @@ ActionSpec.configure { |config|
 }
 ```
 
+If you want to override one specific field directly in the DSL, use `error` or `error_message` on that field:
+
+```ruby
+doc {
+  query! :page, Integer, error: "choose a page first"
+  query :role, String, validate: -> { false }, error_message: -> { "is not allowed for #{current_user}" }
+  json data: {
+    birthday!: { type: Date, error_message: ->(error, value) { "#{error}: #{value.inspect}" } }
+  }
+}
+```
+
 ## AI Generation Style Guide
 
 When using AI tools to generate Rails controller code, and the change involves parameter validation, type coercion, default values, or similar parameter contracts, these conventions work well with ActionSpec:
@@ -640,6 +826,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/configuration.rb

@@ -3,7 +3,7 @@
 module ActionSpec
   class Configuration
     attr_accessor :invalid_parameters_exception_class, :open_api_output, :open_api_title, :open_api_version,
-                  :open_api_server_url, :default_response_media_type
+                  :open_api_server_url, :default_response_media_type, :required_allow_blank
     attr_reader :error_messages
 
     def initialize
@@ -13,6 +13,7 @@ module ActionSpec
       @open_api_version = nil
       @open_api_server_url = nil
       @default_response_media_type = :json
+      @required_allow_blank = true
       @error_messages = ActiveSupport::HashWithIndifferentAccess.new
     end
 
@@ -35,6 +36,7 @@ module ActionSpec
         copy.open_api_version = open_api_version
         copy.open_api_server_url = open_api_server_url
         copy.default_response_media_type = default_response_media_type
+        copy.required_allow_blank = required_allow_blank
         copy.error_messages = error_messages.deep_dup
       end
     end

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