action_spec 0.2.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bf40844c78d8e8281f129c65e12bf07d9fc8ebabc18bd47c717d779cbc90fa99
-  data.tar.gz: 1552ea6a7da3f13b02febfd4eea39b05b437db5efaa93bb99320662b9f96e98c
+  metadata.gz: 0adf599aac952bde5c1969385d71ea5a023fe20814abd835a8ab55dca32ca319
+  data.tar.gz: 6761792a92ae44fd93b7fad87d350d952494ff6c3b7bc17023ae5fd7020d373f
 SHA512:
-  metadata.gz: 02e508bf9545f6848c351d96e7b95d4b7f22219322d365bba632f793722899922ee9ef347c147d4c98987cc9bf9b1ef18f70436ba105a7e695d0bb96f92acb47
-  data.tar.gz: cb9023dc36b73d1c155854200d726eb3fe3cb1dea03734da8fde6f64cf93cf58a2376eba90e77ccaff66c29ecbda220c6376037608a5d9fb2c0be702192c51f4
+  metadata.gz: 5490efab1cd187ab21a97c10401dc3471c81dccc161e40955b5e53cb2f9b5cacf375cb55cbed382bc19f47e7bd0b9f69aa870c4ca0bf9f78663b6f89e1973d74
+  data.tar.gz: ee1d9eb0eaacbbc8df53b5db72568006dde268ecf400f0de4f60087ee60511a51fde327716c5a23612398dd01a0f6e37665123569f28e9e95bba32bd74a03107

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 one hour, 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 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.
 
 ## Table Of Contents
 
@@ -16,10 +16,11 @@ Concise and Powerful API Documentation Solution for Rails.
   - [`doc_dry`](#doc_dry)
   - [DSL Reference](#dsl-reference)
 - [Schemas](#schemas)
-  - [Required Fields](#required-fields)
-  - [Supported Runtime Types](#supported-runtime-types)
+  - [Declare A Required Field](#declare-a-required-field)
+  - [Field Types](#field-types)
+  - [Field Options](#field-options)
+  - [Schemas From ActiveRecord](#schemas-from-activerecord)
   - [Type And Boundary Matrix](#type-and-boundary-matrix)
-  - [Supported Runtime Options](#supported-runtime-options)
 - [Parameter Validation And Type Coercion](#parameter-validation-and-type-coercion)
   - [Validation Flow](#validation-flow)
   - [Reading Validated Values With `px`](#reading-validated-values-with-px)
@@ -250,7 +251,7 @@ Response declarations are stored as metadata now. They are not yet used to rende
 
 ## Schemas
 
-#### Required Fields
+#### Declare A Required Field
 
 Use `!` in either place:
 
@@ -271,7 +272,7 @@ Meaning of `!`:
 - keys such as `name!:` or `nickname!:` mark nested object fields as required
 - `body!`, `json!`, and `form!` are currently accepted for DSL consistency, but today they behave the same as the non-bang form at runtime
 
-#### Supported Runtime Types
+#### Field Types
 
 Scalar types currently supported by validation/coercion:
 
@@ -294,28 +295,12 @@ json data: {
   profile: {
     nickname!: String
   },
-  settings: { type: Object }
+  settings: { type: Object },
+  users: [{ id: Integer }]
 }
 ```
 
-#### Type And Boundary Matrix
-
-| Type | Accepted examples | Rejected examples / notes |
-| --- | --- | --- |
-| `String` | `12`, `true`, `""` | Follows `ActiveModel::Type::String`, so `true` becomes `"t"` |
-| `Integer` | `"0"`, `"-12"`, `"+7"`, `12` | Rejects `"12.3"`, `"abc"`, `""` |
-| `Float` | `"0"`, `"-12.5"`, `12`, `12.5` | Rejects `"12.3.4"`, `"abc"` |
-| `BigDecimal` | `"0"`, `"-12.50"`, `12`, `12.5` | Rejects `"abc"` |
-| `:boolean` / host-defined `Boolean` | `true`, `false`, `"1"`, `"0"`, `"true"`, `"false"`, `"yes"`, `"no"`, `"on"`, `"off"` | Rejects ambiguous values such as `""`, `"2"`, `"TRUE "`, `"maybe"` |
-| `Date` | `"2025-10-17"` | Rejects invalid dates such as `"2025-02-30"` |
-| `DateTime` | `"2025-10-17T12:30:00Z"` | Rejects invalid datetimes such as `"2025-10-17 25:00:00"` |
-| `Time` | `"2025-10-17T12:30:00Z"` | Follows `ActiveModel::Type::Time`, so the date part becomes `2000-01-01` |
-| `File` | `ActionDispatch::Http::UploadedFile`, `Tempfile`, file-like IO objects | Keeps the object as-is and does not read file contents into memory |
-| `Object` | `Hash`, `ActionController::Parameters`, arbitrary Ruby objects | Passed through for scalar `Object`; nested hashes use object schema resolution |
-| `[Type]` | arrays such as `%w[1 2 3]` for `[Integer]` | Rejects non-array values, and reports item errors like `tags.1` |
-| nested object | `{ profile: { nickname: "neo" } }` | Rejects non-hash values, and reports nested paths like `profile.nickname` |
-
-#### Supported Runtime Options
+#### Field Options
 
 These options are currently used by the validator:
 
@@ -327,14 +312,85 @@ query :score, Integer, range: { ge: 1, le: 5 }
 query :slug, String, pattern: /\A[a-z\-]+\z/
 ```
 
-These options are currently accepted as metadata, mainly for future OpenAPI work, but are not yet used by the runtime validator:
+These options are currently used by OpenAPI generation, but are not yet used by the runtime validator:
 
 - `desc`
 - `example`
 - `examples`
+
+These options are not yet used by either the runtime validator or OpenAPI generation:
+
 - `allow_nil`
 - `allow_blank`
 
+#### Schemas From ActiveRecord
+
+If your model is an `ActiveRecord::Base`, you can derive an ActionSpec-friendly schema hash directly from the model:
+
+```ruby
+class UsersController < ApplicationController
+  doc {
+    form data: User.schemas
+  }
+  def create
+  end
+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:
+
+```ruby
+User.schemas
+```
+
+You can also limit the exported fields:
+
+```ruby
+User.schemas(only: %i[name phone role])
+```
+
+ActionSpec extracts schema-relevant information from ActiveRecord / ActiveModel when available, including:
+
+- field type
+- requiredness, rendered as bang keys such as `"name!"`
+- enum values from `enum`
+- `default`
+- `desc` from column comments
+- `pattern` from format validators
+- `range` from numericality validators
+- `length` from length validators and string column limits
+
+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] }
+# }
+```
+
+#### Type And Boundary Matrix
+
+| Type | Accepted examples | Rejected examples / notes |
+| --- | --- | --- |
+| `String` | `12`, `true`, `""` | Follows `ActiveModel::Type::String`, so `true` becomes `"t"` |
+| `Integer` | `"0"`, `"-12"`, `"+7"`, `12` | Rejects `"12.3"`, `"abc"`, `""` |
+| `Float` | `"0"`, `"-12.5"`, `12`, `12.5` | Rejects `"12.3.4"`, `"abc"` |
+| `BigDecimal` | `"0"`, `"-12.50"`, `12`, `12.5` | Rejects `"abc"` |
+| `:boolean` / `Boolean` | `true`, `false`, `"1"`, `"0"`, `"true"`, `"false"`, `"yes"`, `"no"`, `"on"`, `"off"` | Rejects ambiguous values such as `""`, `"2"`, `"TRUE "`, `"maybe"` |
+| `Date` | `"2025-10-17"` | Rejects invalid dates such as `"2025-02-30"` |
+| `DateTime` | `"2025-10-17T12:30:00Z"` | Rejects invalid datetimes such as `"2025-10-17 25:00:00"` |
+| `Time` | `"2025-10-17T12:30:00Z"` | Follows `ActiveModel::Type::Time`, so the date part becomes `2000-01-01` |
+| `File` | `ActionDispatch::Http::UploadedFile`, `Tempfile`, file-like IO objects | Keeps the object as-is and does not read file contents into memory |
+| `Object` | `Hash`, `ActionController::Parameters`, arbitrary Ruby objects | Passed through for scalar `Object`; nested hashes use object schema resolution |
+| `[Type]` | arrays such as `%w[1 2 3]` for `[Integer]` | Rejects non-array values, and reports item errors like `tags.1` |
+| nested object | `{ profile: { nickname: "neo" } }` | Rejects non-hash values, and reports nested paths like `profile.nickname` |
+
+
 ## Parameter Validation And Type Coercion
 
 ### Validation Flow
@@ -501,7 +557,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:
@@ -529,10 +585,24 @@ end
 
 ## What Is Not Implemented Yet
 
-- OpenAPI document generation
-- automatic response rendering from `response`
-- reusable schema/components system from `zero-rails_openapi`
-- runtime behavior for `allow_nil` / `allow_blank`
+- reusable `components` generation
+- `$ref` generation and deduplication
+- `description`, `operationId`, `tags`, `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
+- response body schema generation; current `response` / `resp` / `error` declarations only generate response descriptions
+- response headers
+- response links
+- callbacks
+- webhooks
+- path-level shared parameters
+- top-level `components.parameters`, `components.requestBodies`, `components.responses`, `components.headers`, `components.examples`, `components.links`, `components.callbacks`, `components.schemas`, `components.securitySchemes`, and `components.pathItems`
+- top-level `security`
+- top-level `tags`
+- top-level `externalDocs`
+- `jsonSchemaDialect`
+- 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
 .

data/lib/action_spec/open_api/generator.rb

@@ -53,7 +53,9 @@ module ActionSpec
             next if path.blank?
 
             hash[path] ||= ActiveSupport::OrderedHash.new
-            hash[path][route_verb(route)] = Operation.new(endpoint).build
+            route_verbs(route).each do |verb|
+              hash[path][verb] = Operation.new(endpoint).build
+            end
           end
         end
 
@@ -87,7 +89,7 @@ module ActionSpec
           defaults.to_h.symbolize_keys
         end
 
-        def route_verb(route)
+        def route_verbs(route)
           raw_verb =
             if route.respond_to?(:verb) && route.verb.respond_to?(:source)
               route.verb.source
@@ -97,7 +99,7 @@ module ActionSpec
               route[:verb].to_s
             end
 
-          raw_verb.gsub(/[$^]/, "").split("|").find(&:present?).to_s.downcase
+          raw_verb.gsub(/[$^]/, "").split("|").filter_map { |verb| verb.presence&.downcase }
         end
 
         def normalized_path(route)

data/lib/action_spec/open_api/schema.rb

@@ -108,6 +108,7 @@ module ActionSpec
           definition["default"] = schema.default unless schema.default.respond_to?(:call) || schema.default.nil?
           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_range(definition, schema.range)
@@ -124,6 +125,16 @@ module ActionSpec
           definition["exclusiveMaximum"] = rules[:lt] if rules.key?(:lt)
         end
 
+        def apply_length(definition, length, type)
+          return if length.blank?
+
+          rules = length.symbolize_keys
+          return unless type == "string"
+
+          definition["minLength"] = rules[:minimum] if rules.key?(:minimum)
+          definition["maxLength"] = rules[:maximum] if rules.key?(:maximum)
+        end
+
         def scalar_type(type)
           case ActionSpec::Schema::TypeCaster.normalize(type)
           when :string then "string"

data/lib/action_spec/railtie.rb

@@ -1,14 +1,16 @@
 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
         include ActionSpec::Validator
       end
     end
+
+    initializer "action_spec.active_record" do
+      ActiveSupport.on_load(:active_record) do
+        include ActionSpec::Schema::ActiveRecord
+      end
+    end
   end
 end

data/lib/action_spec/schema/active_record.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module ActionSpec
+  module Schema
+    module ActiveRecord
+      extend ActiveSupport::Concern
+
+      class_methods do
+        def schemas(only: nil)
+          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)
+          end
+        ensure
+          remove_instance_variable(:@action_spec_validator_index) if instance_variable_defined?(:@action_spec_validator_index)
+        end
+
+        private
+
+          def selected_column_names(only)
+            selected = Array(only).presence&.map { |name| normalize_name(name) } || column_names
+
+            column_names.select { |name| selected.include?(name) }
+          end
+
+          def output_name(name)
+            required_attribute?(name) ? "#{name}!" : name
+          end
+
+          def schema_definition_for(name)
+            definition = { type: schema_type_for(name) }
+            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?
+            definition[:pattern] = pattern_for(name) if pattern_for(name)
+            definition[:range] = range_for(name) if range_for(name).present?
+            definition[:length] = length_for(name) if length_for(name).present?
+            definition
+          end
+
+          def schema_type_for(name)
+            return String if enum_values_for(name).present?
+
+            case columns_hash.fetch(name).type
+            when :string, :text, :binary then String
+            when :integer, :bigint then Integer
+            when :float then Float
+            when :decimal then BigDecimal
+            when :boolean then :boolean
+            when :date then Date
+            when :datetime, :timestamp then DateTime
+            when :time then Time
+            when :json, :jsonb then Object
+            else String
+            end
+          end
+
+          def required_attribute?(name)
+            (!column_nullable?(name) && column_default_for(name).nil?) || presence_validated?(name)
+          end
+
+          def column_nullable?(name)
+            columns_hash.fetch(name).null
+          end
+
+          def column_default_for(name)
+            columns_hash.fetch(name).default
+          end
+
+          def column_comment_for(name)
+            columns_hash.fetch(name).comment
+          end
+
+          def enum_values_for(name)
+            defined_enums.fetch(name.to_s, nil)&.keys
+          end
+
+          def inclusion_values_for(name)
+            validator_for(name, ActiveModel::Validations::InclusionValidator)&.options&.fetch(:in, nil)&.to_a
+          end
+
+          def resolved_enum_for(name)
+            enum_values_for(name).presence || inclusion_values_for(name).presence
+          end
+
+          def pattern_for(name)
+            validator_for(name, ActiveModel::Validations::FormatValidator)&.options&.fetch(:with, nil)
+          end
+
+          def range_for(name)
+            options = validator_for(name, ActiveModel::Validations::NumericalityValidator)&.options
+            return if options.blank?
+
+            {}.tap do |range|
+              range[:gt] = options[:greater_than] if options.key?(:greater_than)
+              range[:ge] = options[:greater_than_or_equal_to] if options.key?(:greater_than_or_equal_to)
+              range[:lt] = options[:less_than] if options.key?(:less_than)
+              range[:le] = options[:less_than_or_equal_to] if options.key?(:less_than_or_equal_to)
+            end.presence
+          end
+
+          def length_for(name)
+            definition = {}.tap do |length|
+              limit = string_limit_for(name)
+              length[:maximum] = limit if limit
+
+              options = validator_for(name, ActiveModel::Validations::LengthValidator)&.options || {}
+              length[:minimum] = options[:minimum] if options.key?(:minimum)
+              length[:maximum] = options[:maximum] if options.key?(:maximum)
+
+              if options.key?(:is)
+                length[:minimum] = options[:is]
+                length[:maximum] = options[:is]
+              end
+            end
+
+            definition.presence
+          end
+
+          def string_limit_for(name)
+            column = columns_hash.fetch(name)
+            return unless column.type.in?([:string, :text])
+
+            column.limit
+          end
+
+          def presence_validated?(name)
+            validator_for(name, ActiveModel::Validations::PresenceValidator).present?
+          end
+
+          def validator_for(name, klass)
+            validator_index.fetch(name.to_s, []).find { |validator| validator.is_a?(klass) }
+          end
+
+          def normalize_name(name)
+            name.to_s.delete_suffix("!")
+          end
+
+          def build_validator_index
+            validators.each_with_object(Hash.new { |hash, key| hash[key] = [] }) do |validator, index|
+              validator.attributes.each do |attribute|
+                index[attribute.to_s] << validator
+              end
+            end
+          end
+
+          def validator_index
+            @action_spec_validator_index ||= build_validator_index
+          end
+      end
+    end
+  end
+end

data/lib/action_spec/schema/array_of.rb

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

data/lib/action_spec/schema/base.rb

@@ -3,7 +3,7 @@
 module ActionSpec
   module Schema
     class Base
-      attr_reader :default, :enum, :range, :pattern, :allow_nil, :allow_blank, :description, :example, :examples
+      attr_reader :default, :enum, :range, :pattern, :length, :allow_nil, :allow_blank, :description, :example, :examples
 
       def initialize(options = {})
         options = options.symbolize_keys
@@ -11,6 +11,7 @@ module ActionSpec
         @enum = options[:enum]
         @range = options[:range]
         @pattern = options[:pattern]
+        @length = options[:length]
         @allow_nil = options[:allow_nil]
         @allow_blank = options[:allow_blank]
         @description = options[:desc] || options[:description]

data/lib/action_spec/schema/object_of.rb

@@ -34,7 +34,7 @@ module ActionSpec
       end
 
       def copy
-        self.class.new(fields.transform_values(&:copy), default:, enum:, range:, pattern:, allow_nil:, allow_blank:, desc: description, example:, examples:)
+        self.class.new(fields.transform_values(&:copy), default:, enum:, range:, pattern:, length:, allow_nil:, allow_blank:, desc: description, example:, examples:)
       end
 
       private

data/lib/action_spec/schema/scalar.rb

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

data/lib/action_spec/schema.rb

@@ -5,13 +5,14 @@ require "action_spec/schema/field"
 require "action_spec/schema/scalar"
 require "action_spec/schema/object_of"
 require "action_spec/schema/array_of"
+require "action_spec/schema/active_record"
 require "action_spec/schema/resolver"
 require "action_spec/schema/type_caster"
 
 module ActionSpec
   module Schema
     Missing = Object.new.freeze
-    OPTION_KEYS = %i[default desc enum range pattern allow_nil allow_blank example examples].freeze
+    OPTION_KEYS = %i[default desc enum range pattern length allow_nil allow_blank example examples].freeze
 
     class << self
       def build(type = nil, **options)

data/lib/action_spec/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: action_spec
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 1.1.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: []
@@ -69,6 +69,7 @@ files:
 - lib/action_spec/open_api/schema.rb
 - lib/action_spec/railtie.rb
 - lib/action_spec/schema.rb
+- lib/action_spec/schema/active_record.rb
 - lib/action_spec/schema/array_of.rb
 - lib/action_spec/schema/base.rb
 - lib/action_spec/schema/field.rb
@@ -86,8 +87,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