action_spec 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6fccbffa8f14fb73bec7eade75add8f70d0371741999475ef292ed980d985ddc
-  data.tar.gz: 20f1b1d3b86826b1cb9d2ed3d72f0259ccd28c397790bbf8bc8fb8766cab0329
+  metadata.gz: a01ddc76d37b180c1564c96963ccce0bbe32cc9efd4c29deede6e1c3e7a8f7c7
+  data.tar.gz: a97df2927f2f5df0fce593b2ff55fa123d983ab6023690326bce9634ead51b31
 SHA512:
-  metadata.gz: 552c83ccebe73754cb2b6e160cbfb8774ea818e22e665a1ba6df322c5051e5ff7902b533d82c2c2a93f94fd0f631264e2e344521b67a3582576a27b5f4ce2144
-  data.tar.gz: 9585aa85edeb6654d00e06b7a0e2478aed741675d3d90e0b60c46ac99d267e68d13bbe30060f6b163b1869ac508b92c4509b8b0b0f69f3ae7d0c386da875afce
+  metadata.gz: e5ba8be1ae92c054686603867e11cda5b1af8482113ae2fcd4b36303e9631f1bdfd3c915b5e724a84dcd3c20c29f2a3f46bb92f74654716c3037625125d00820
+  data.tar.gz: 0d8327b6f04162da2ceedf697ac0a0e3dde789584870ebde8c2769ac43e6bb00836a81386b61d519b2472cd4acd8ffaf19472bbd0490c7911f9295c5216d4ed4

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
 
@@ -23,9 +23,8 @@ 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)
@@ -106,6 +105,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 +150,27 @@ 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`.
 
+You can also opt an action out of OpenAPI generation from either `doc` or `doc_dry`:
+
+```ruby
+doc {
+  openapi false
+}
+```
+
 ### DSL Reference
 
 #### Parameter
@@ -238,6 +246,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 +374,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 +444,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 +460,41 @@ 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.
 
 ```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 +503,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
-
-By default, when a controller raises `ActionSpec::InvalidParameters`, ActionSpec catches it automatically and returns a JSON error response:
-
-```ruby
-rescue_from ActionSpec::InvalidParameters
-```
+`error.message` is built from `error.errors.full_messages.to_sentence`, so it follows normal `ActiveModel::Errors` wording:
 
-The default JSON response is:
+- 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"`
 
-```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 +548,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.
@@ -557,7 +570,7 @@ Available config keys:
 
 ### I18n
 
-ActionSpec loads its own locale files and uses `ActiveModel::Errors`, so you can override both messages and attribute names:
+ActionSpec uses `ActiveModel::Errors`, so you can override both messages and attribute names:
 
 ```yml
 en:
@@ -574,13 +587,13 @@ 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
+}
 ```
 
 ## What Is Not Implemented Yet
@@ -605,7 +618,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/open_api/generator.rb

@@ -48,6 +48,7 @@ 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?

data/lib/action_spec/railtie.rb

@@ -1,9 +1,5 @@
 module ActionSpec
   class Railtie < ::Rails::Railtie
-    initializer "action_spec.i18n" do |app|
-      app.config.i18n.load_path += Dir[root.join("config/locales/*.yml")]
-    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.0.0"
+  VERSION = "1.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: action_spec
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - zhandao
@@ -43,7 +43,7 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '9.0'
-description: Concise and Powerful API Documentation Solution for Rails.
+description: A concise Rails DSL for declaring API request and response schemas.
 email:
 - a@skipping.cat
 executables: []
@@ -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
@@ -87,8 +85,8 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/action-spec/action_spec
-  source_code_uri: https://github.com/action-spec/action_spec
-  changelog_uri: https://github.com/action-spec/action_spec/CHANils.
+  source_code_uri: https://github.com/action-spec/action_spec/tree/main
+  changelog_uri: https://github.com/action-spec/action_spec/releases
 rdoc_options: []
 require_paths:
 - lib

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}"