action_spec 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0adf599aac952bde5c1969385d71ea5a023fe20814abd835a8ab55dca32ca319
-  data.tar.gz: 6761792a92ae44fd93b7fad87d350d952494ff6c3b7bc17023ae5fd7020d373f
+  metadata.gz: 02c55ca1816d1b61ad17a4a735c1704bb887cc4f67d842a7ed351641c47e93d8
+  data.tar.gz: a148b5f034a92b4f6648c3deb5e29aa997588e6162cd761e3586e9840d6b0fa2
 SHA512:
-  metadata.gz: 5490efab1cd187ab21a97c10401dc3471c81dccc161e40955b5e53cb2f9b5cacf375cb55cbed382bc19f47e7bd0b9f69aa870c4ca0bf9f78663b6f89e1973d74
-  data.tar.gz: ee1d9eb0eaacbbc8df53b5db72568006dde268ecf400f0de4f60087ee60511a51fde327716c5a23612398dd01a0f6e37665123569f28e9e95bba32bd74a03107
+  metadata.gz: 1eb2aa363f52d5800497364315168186b3fb04fc0fc1541ebe2075a73284585a5302b68f48183f5163451607f53bddc42474a988a6549dcb4daf7849bd2bf9aa
+  data.tar.gz: 985e5bd7551b4f6bd9919209137c90cae86a3a2720113dacb01e421849fca4e16a602550fb833a920d703f997c97a2b8b87c49ceda5ce4ecefa9bfea1a641988

data/README.md

@@ -6,7 +6,7 @@ Concise and Powerful API Documentation Solution for Rails.
 
 - OpenAPI version: `v3.2.0`
 - Requires: Ruby 3.1+ and Rails 7.0+
-- Note: this project was implemented with Codex in about 2 hours, has not yet been manually reviewed, and has not been validated in production. It does, however, come with fairly detailed RSpec tests generated with Codex.
+- Note: this project was implemented with Codex in about 3 hours, has not yet been manually reviewed, and has not been validated in production. It does, however, come with fairly detailed RSpec tests generated with Codex.
 
 ## Table Of Contents
 
@@ -14,6 +14,8 @@ Concise and Powerful API Documentation Solution for Rails.
 - [Doc DSL](#doc-dsl)
   - [`doc`](#doc)
   - [`doc_dry`](#doc_dry)
+  - [`openapi false`](#openapi-false)
+  - [`tag`](#tag)
   - [DSL Reference](#dsl-reference)
 - [Schemas](#schemas)
   - [Declare A Required Field](#declare-a-required-field)
@@ -23,12 +25,12 @@ Concise and Powerful API Documentation Solution for Rails.
   - [Type And Boundary Matrix](#type-and-boundary-matrix)
 - [Parameter Validation And Type Coercion](#parameter-validation-and-type-coercion)
   - [Validation Flow](#validation-flow)
-  - [Reading Validated Values With `px`](#reading-validated-values-with-px)
+  - [Reading Processed Values With `px`](#reading-processed-values-with-px)
   - [Errors](#errors)
-  - [Default Rescue Behavior](#default-rescue-behavior)
 - [Configuration And I18n](#configuration-and-i18n)
   - [Configuration](#configuration)
   - [I18n](#i18n)
+- [AI Generation Style Guide](#ai-generation-style-guide)
 
 ## Example
 
@@ -106,6 +108,7 @@ bin/rails action_spec:gen \
 Notes:
 
 - only routed controller actions with a matching `doc` declaration are included
+- endpoints with `openapi false` are skipped even when routed
 - Rails paths such as `/users/:id(.:format)` are rendered as `/users/{id}`
 - parameters, request bodies, and response descriptions are generated from the current DSL support
 - if config and environment variables do not provide `TITLE` or `VERSION`, ActionSpec falls back to application-derived defaults
@@ -150,19 +153,43 @@ end
 
 ```ruby
 class ApplicationController < ActionController::API
-  doc_dry %i[show update destroy] do
+  doc_dry(%i[show update destroy]) {
     path! :id, Integer
-  end
+  }
 
-  doc_dry :index do
+  doc_dry(:index) {
     query :page, Integer, default: 1
     query :per, Integer, default: 20
-  end
+  }
 end
 ```
 
 All matching dry blocks are applied before the action-specific `doc`.
 
+### `openapi false`
+
+You can also opt an action out of OpenAPI generation from either `doc` or `doc_dry`:
+
+```ruby
+doc {
+  openapi false
+}
+```
+
+### `tag`
+
+OpenAPI tags can also be set at either level:
+
+```ruby
+doc_dry(:index, tag: "backoffice")
+
+doc("List users", tag: "members") {
+  query :status, String
+}
+```
+
+Generated OpenAPI operations also include an `operationId`, built from the final tag plus the action name, for example `members_index` or `users_create`.
+
 ### DSL Reference
 
 #### Parameter
@@ -238,6 +265,33 @@ data :file, File
 
 For `body/body!`, `json/json!`, and `form/form!`, the bang form is currently kept for DSL compatibility. At runtime they all contribute to the same body contract, and root-body requiredness is not yet enforced as a separate rule.
 
+#### OpenAPI
+
+```ruby
+openapi false
+```
+
+Use this when an action should stay out of the generated OpenAPI document. It also works inside `doc_dry`.
+
+#### Scope
+
+Use `scope` when you want a grouped view that spans multiple request locations:
+
+```ruby
+doc {
+  scope(:user) {
+    query :user_id, Integer
+    form data: { name: String }
+  }
+}
+```
+
+Then read it from `px.scope`:
+
+```ruby
+px.scope[:user] # => { user_id: 1, name: "Tom" }
+```
+
 #### Response 
 
 ```ruby
@@ -339,7 +393,7 @@ end
 
 `User.schemas` returns a hash that can be passed directly into `form data:`, `json data:`, or `body`.
 
-By default it includes all model fields:
+By default, it includes all model fields:
 
 ```ruby
 User.schemas
@@ -409,6 +463,8 @@ Example:
 - DSL says `query :page, Integer`
 - result: `px[:page] == "2"`
 
+You can safely put this hook on a base controller. If the current action has no matching `doc`, ActionSpec skips validation and returns an empty `px`.
+
 #### `validate_and_coerce_params!`
 
 Validates and coerces values before exposing them on `px`.
@@ -423,36 +479,42 @@ Example:
 - DSL says `query :page, Integer`
 - result: `px[:page] == 2`
 
-### Reading Validated Values With `px`
+This hook also skips actions without a matching `doc`, so it is safe to declare on a shared base controller.
 
-`px` is a hash.
+### Reading Processed Values With `px`
+
+`px` stores the processed values produced by ActionSpec. With `validate_params!` they stay raw; with `validate_and_coerce_params!` they are coerced values.
+Because `px` is still a hash, you can also use helpers such as `px.slice(...)` to simplify parameter access code.
 
 ```ruby
 px[:id]
 px[:page]
 px[:profile][:nickname]
 px.to_h
+px.scope[:user]
 ```
 
-It also includes grouped buckets:
+Grouped views live under `px.scope`:
 
 ```ruby
-px[:path]
-px[:query]
-px[:body]
-px[:headers]
-px[:cookies]
+px.scope[:path]
+px.scope[:query]
+px.scope[:body]
+px.scope[:headers]
+px.scope[:cookies]
 ```
 
 Notes:
 
-- root values from path/query/body are also flattened into `px[:name]`
+- 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]`
+- 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:
 
 ```ruby
-px[:headers][:authorization]
-px[:headers]["Authorization"]
-px[:headers]["HTTP_AUTHORIZATION"]
+px.scope[:headers][:authorization]
+px.scope[:headers]["Authorization"]
+px.scope[:headers]["HTTP_AUTHORIZATION"]
 ```
 
 - original `params` are not mutated
@@ -461,60 +523,43 @@ px[:headers]["HTTP_AUTHORIZATION"]
 
 Validation errors are stored in `ActiveModel::Errors`.
 
-If invalid parameters are not rescued, ActionSpec raises `ActionSpec::InvalidParameters`:
+When validation fails, ActionSpec raises `ActionSpec::InvalidParameters`:
 
 ```ruby
 begin
   validate_and_coerce_params!
 rescue ActionSpec::InvalidParameters => error
+  error.message
   error.errors.full_messages
 end
 ```
 
 The exception also keeps the full validation result on `error.result` and `error.parameters`.
+ActionSpec does not render a default error response for you, so each application can decide its own rescue and JSON format.
 
-### Default Rescue Behavior
+`error.message` is built from `error.errors.full_messages.to_sentence`, so it follows normal `ActiveModel::Errors` wording:
 
-By default, when a controller raises `ActionSpec::InvalidParameters`, ActionSpec catches it automatically and returns a JSON error response:
+- single error: `"Page is required"`
+- multiple errors: `"Page is required and Birthday must be a valid date"`
+- fallback when no detailed errors are present: `"Invalid parameters"`
 
-```ruby
-rescue_from ActionSpec::InvalidParameters
-```
-
-The default JSON response is:
-
-```json
-{
-  "errors": {
-    "page": ["Page is required"]
-  }
-}
-```
+Use `error.errors` when you need structured details, and `error.message` when you only need a single summary string.
 
 ## Configuration And I18n
 
 ### Configuration
 
 ```ruby
-ActionSpec.configure do |config|
-  config.rescue_invalid_parameters = true
-  config.invalid_parameters_status = :bad_request
+ActionSpec.configure { |config|
   config.open_api_output = "docs/openapi.yml"
   config.open_api_title = "My API"
   config.open_api_version = "2026.03"
   config.open_api_server_url = "https://api.example.com"
 
-  config.error_messages[:invalid_type] = ->(_attribute, options) do
+  config.error_messages[:invalid_type] = ->(_attribute, options) {
     "should be coercible to #{options.fetch(:expected)}"
-  end
-
-  config.invalid_parameters_renderer = ->(controller, error) do
-    controller.render json: {
-      code: "invalid_parameters",
-      errors: error.errors.to_hash(full_messages: true)
-    }, status: :unprocessable_entity
-  end
-end
+  }
+}
 ```
 
 Available config keys:
@@ -523,18 +568,6 @@ Available config keys:
   Default: `ActionSpec::InvalidParameters`.
   Controls which exception class is raised when validation fails.
 
-- `invalid_parameters_status`
-  Default: `:bad_request`.
-  Controls the HTTP status used by the built-in `rescue_from` renderer.
-
-- `rescue_invalid_parameters`
-  Default: `true`.
-  When this option is enabled, controllers use the default `rescue_from ActionSpec::InvalidParameters`.
-
-- `invalid_parameters_renderer`
-  Default: `nil`.
-  Lets you replace the built-in JSON error response. It can be a proc receiving `(controller, error)`, or a block executed in controller context.
-
 - `error_messages`
   Default: `{}`.
   Lets you override error messages by error type, or by attribute plus error type.
@@ -574,20 +607,32 @@ en:
 You can also override messages per error type or per attribute in Ruby:
 
 ```ruby
-ActionSpec.configure do |config|
+ActionSpec.configure { |config|
   config.error_messages[:required] = "must be present"
   config.error_messages[:invalid_type] = ->(_attribute, options) { "must be a valid #{options.fetch(:expected)}" }
   config.error_messages[:page] = {
     required: "page is mandatory"
   }
-end
+}
 ```
 
+## 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:
+
+- use `doc { }` or `doc("Summary") { }`; do not add the action name, and do not leave a blank line between the `doc` block and the action method
+- use `{ }` blocks inside `doc` as well; prefer them over `do ... end`
+- 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 `doc_dry`, `scope`, and `px.slice` to reduce repetition in controllers
+- when request parameters match model declarations, prefer `.schemas` to keep `doc` concise
+
 ## What Is Not Implemented Yet
 
 - reusable `components` generation
 - `$ref` generation and deduplication
-- `description`, `operationId`, `tags`, `externalDocs`, `deprecated`, and `security` on operations
+- `description`, `externalDocs`, `deprecated`, and `security` on operations
 - parameter-level `style`, `explode`, `allowReserved`, `examples`, and richer header/cookie serialization controls
 - request body `encoding`
 - multiple request/response media types beyond the current direct DSL mapping
@@ -605,7 +650,8 @@ end
 - richer schema keywords beyond the current subset, including nullable/blank semantics, object-level constraints, and composition keywords such as `oneOf`, `anyOf`, `allOf`, and `not`
 
 ## Contributing
-.
+
+Contributions / Issues are welcome.
 
 ## License
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/action_spec/configuration.rb

@@ -2,16 +2,12 @@
 
 module ActionSpec
   class Configuration
-    attr_accessor :invalid_parameters_exception_class, :invalid_parameters_status, :rescue_invalid_parameters,
-                  :invalid_parameters_renderer, :open_api_output, :open_api_title, :open_api_version,
+    attr_accessor :invalid_parameters_exception_class, :open_api_output, :open_api_title, :open_api_version,
                   :open_api_server_url
     attr_reader :error_messages
 
     def initialize
       @invalid_parameters_exception_class = ActionSpec::InvalidParameters
-      @invalid_parameters_status = :bad_request
-      @rescue_invalid_parameters = true
-      @invalid_parameters_renderer = nil
       @open_api_output = "docs/openapi.yml"
       @open_api_title = nil
       @open_api_version = nil
@@ -33,9 +29,6 @@ module ActionSpec
     def dup
       self.class.new.tap do |copy|
         copy.invalid_parameters_exception_class = invalid_parameters_exception_class
-        copy.invalid_parameters_status = invalid_parameters_status
-        copy.rescue_invalid_parameters = rescue_invalid_parameters
-        copy.invalid_parameters_renderer = invalid_parameters_renderer
         copy.open_api_output = open_api_output
         copy.open_api_title = open_api_title
         copy.open_api_version = open_api_version

data/lib/action_spec/doc/dsl.rb

@@ -7,6 +7,7 @@ module ActionSpec
 
       def initialize(endpoint)
         @endpoint = endpoint
+        @scopes = []
       end
 
       PARAM_LOCATIONS.each do |location_name|
@@ -55,6 +56,17 @@ module ActionSpec
         add_body(:form, { name => options.merge(type:) })
       end
 
+      def scope(name, &block)
+        scopes.push(name.to_sym)
+        instance_exec(&block)
+      ensure
+        scopes.pop
+      end
+
+      def openapi(enabled)
+        endpoint.options[:openapi] = enabled
+      end
+
       def response(code, description = nil, media_type = nil, desc: nil, **options)
         endpoint.add_response(
           code,
@@ -73,10 +85,11 @@ module ActionSpec
       private
 
         attr_reader :endpoint
+        attr_reader :scopes
 
         def add_param(location_name, name, type, required:, **options)
           schema = ActionSpec::Schema.build(type, **options)
-          endpoint.request.add_param(location_name, ActionSpec::Schema::Field.new(name:, required:, schema:))
+          endpoint.request.add_param(location_name, ActionSpec::Schema::Field.new(name:, required:, schema:, scopes: scopes.dup))
         end
 
         def add_many(location_name, params, required:)
@@ -86,7 +99,12 @@ module ActionSpec
               if (schema_options.keys - ActionSpec::Schema::OPTION_KEYS).present?
                 endpoint.request.add_param(
                   location_name,
-                  ActionSpec::Schema::Field.new(name:, required:, schema: ActionSpec::Schema.from_definition(definition))
+                  ActionSpec::Schema::Field.new(
+                    name:,
+                    required:,
+                    schema: ActionSpec::Schema.from_definition(definition),
+                    scopes: scopes.dup
+                  )
                 )
               else
                 add_param(location_name, name, String, required:, **definition)
@@ -100,7 +118,7 @@ module ActionSpec
         end
 
         def add_body(media_type, definition)
-          ActionSpec::Schema.build_fields(definition).each_value do |field|
+          ActionSpec::Schema.build_fields(definition, scopes: scopes.dup).each_value do |field|
             endpoint.request.add_body(media_type, field)
           end
         end

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)
@@ -48,13 +65,14 @@ module ActionSpec
             next unless (controller = controller_for(route))
             next unless controller.respond_to?(:action_spec_for)
             next unless (endpoint = controller.action_spec_for(route_action(route)))
+            next if endpoint.options[:openapi] == false
 
             path = normalized_path(route)
             next if path.blank?
 
             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|

data/lib/action_spec/open_api/schema.rb

@@ -105,16 +105,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 +173,31 @@ 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
     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/field.rb

@@ -3,12 +3,13 @@
 module ActionSpec
   module Schema
     class Field
-      attr_reader :name, :schema
+      attr_reader :name, :schema, :scopes
 
-      def initialize(name:, required:, schema:)
+      def initialize(name:, required:, schema:, scopes: [])
         @name = name.to_sym
         @required = required
         @schema = schema
+        @scopes = Array(scopes).map(&:to_sym).freeze
       end
 
       def required?
@@ -20,7 +21,7 @@ module ActionSpec
       end
 
       def copy
-        self.class.new(name:, required: required?, schema: schema.copy)
+        self.class.new(name:, required: required?, schema: schema.copy, scopes:)
       end
     end
   end

data/lib/action_spec/schema.rb

@@ -40,13 +40,14 @@ module ActionSpec
         ObjectOf.new(build_fields(definition))
       end
 
-      def build_fields(definition_hash)
+      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:
+            schema:,
+            scopes:
           )
         end
       end

data/lib/action_spec/validation_result.rb

@@ -5,26 +5,29 @@ module ActionSpec
     extend ActiveModel::Naming
     extend ActiveModel::Translation
 
+    BUILT_IN_SCOPES = %i[path query body headers cookies].freeze
+
+    class << self
+      def empty_px
+        new.px
+      end
+    end
+
     attr_reader :errors, :px
 
     def initialize
       @errors = ActiveModel::Errors.new(self)
-      @px = ActiveSupport::HashWithIndifferentAccess.new(
-        path: ActiveSupport::HashWithIndifferentAccess.new,
-        query: ActiveSupport::HashWithIndifferentAccess.new,
-        body: ActiveSupport::HashWithIndifferentAccess.new,
-        headers: HeaderHash.new,
-        cookies: ActiveSupport::HashWithIndifferentAccess.new
-      )
+      @px = build_px
     end
 
     def invalid?
       errors.any?
     end
 
-    def assign(location, key, value)
+    def assign(location, key, value, scopes: [])
       bucket(location)[key] = value
       px[key] = value if root_bucket?(location)
+      Array(scopes).each { |scope_name| scope_bucket(scope_name)[key] = value }
     end
 
     def add_error(attribute, type, **options)
@@ -60,8 +63,28 @@ module ActionSpec
 
     private
 
+      def build_px
+        values = ActiveSupport::HashWithIndifferentAccess.new
+        scope = ActiveSupport::HashWithIndifferentAccess.new
+
+        BUILT_IN_SCOPES.each do |scope_name|
+          bucket = scope_name == :headers ? HeaderHash.new : ActiveSupport::HashWithIndifferentAccess.new
+          values[scope_name] = bucket
+          scope[scope_name] = bucket
+        end
+
+        # Keep px hash-like while exposing grouped views through px.scope.
+        values.instance_variable_set(:@scope, scope)
+        values.define_singleton_method(:scope) { @scope }
+        values
+      end
+
       def bucket(location)
-        px.fetch(location)
+        px.scope.fetch(location)
+      end
+
+      def scope_bucket(name)
+        px.scope[name] ||= ActiveSupport::HashWithIndifferentAccess.new
       end
 
       def root_bucket?(location)

data/lib/action_spec/validator/runner.rb

@@ -28,7 +28,7 @@ module ActionSpec
             value = resolve_field(field, result:, source:, location:)
             next if value.equal?(ActionSpec::Schema::Missing)
 
-            result.assign(location, storage_key(field, location), value)
+            result.assign(location, storage_key(field, location), value, scopes: field.scopes)
           end
         end
 

data/lib/action_spec/validator.rb

@@ -6,12 +6,8 @@ module ActionSpec
   module Validator
     extend ActiveSupport::Concern
 
-    included do
-      rescue_from ActionSpec::InvalidParameters, with: :render_invalid_parameters if ActionSpec.config.rescue_invalid_parameters
-    end
-
     def px
-      @px ||= ActiveSupport::HashWithIndifferentAccess.new
+      @px ||= ValidationResult.empty_px
     end
 
     def validate_params!
@@ -26,21 +22,12 @@ module ActionSpec
 
       def validate_with(coerce:)
         endpoint = self.class.respond_to?(:action_spec_for) ? self.class.action_spec_for(action_name) : nil
-        return ActiveSupport::HashWithIndifferentAccess.new unless endpoint
+        return ValidationResult.empty_px unless endpoint
 
         result = Runner.new(endpoint:, controller: self, coerce:).call
         raise ActionSpec.config.invalid_parameters_exception_class.new(result) if result.invalid?
 
         result.px
       end
-
-      def render_invalid_parameters(error)
-        if (renderer = ActionSpec.config.invalid_parameters_renderer)
-          return renderer.arity == 2 ? renderer.call(self, error) : instance_exec(error, &renderer)
-        end
-
-        render json: { errors: error.errors.to_hash(full_messages: true) },
-               status: ActionSpec.config.invalid_parameters_status
-      end
   end
 end

data/lib/action_spec/version.rb

@@ -1,3 +1,3 @@
 module ActionSpec
-  VERSION = "1.1.0"
+  VERSION = "1.3.0"
 end

data/lib/tasks/action_spec_tasks.rake

@@ -2,13 +2,16 @@ namespace :action_spec do
   desc "Generate an OpenAPI 3.2 document from ActionSpec controller docs"
   task gen: :environment do
     config = ActionSpec.config
+    output = Rails.root.join(ENV.fetch("OUTPUT", config.open_api_output)).to_s
 
     ActionSpec::OpenApi::Generator.generate!(
       application: Rails.application,
-      output: Rails.root.join(ENV.fetch("OUTPUT", config.open_api_output)).to_s,
+      output:,
       title: ENV["TITLE"].presence || config.open_api_title,
       version: ENV["VERSION"].presence || config.open_api_version,
       server_url: ENV["SERVER_URL"].presence || config.open_api_server_url
     )
+
+    puts "Generated OpenAPI document: #{output}"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: action_spec
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.3.0
 platform: ruby
 authors:
 - zhandao
@@ -53,8 +53,6 @@ files:
 - MIT-LICENSE
 - README.md
 - Rakefile
-- config/locales/en.yml
-- config/locales/zh.yml
 - lib/action_spec.rb
 - lib/action_spec/configuration.rb
 - lib/action_spec/doc.rb

data/config/locales/en.yml

@@ -1,6 +0,0 @@
-en:
-  activemodel:
-    errors:
-      messages:
-        required: "is required"
-        invalid_type: "must be a valid %{expected}"

data/config/locales/zh.yml

@@ -1,6 +0,0 @@
-zh:
-  activemodel:
-    errors:
-      messages:
-        required: "不能为空"
-        invalid_type: "必须是有效的%{expected}"