action_spec 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 888d8ca36314d55e09ba317663b9fdee4e09895480d0c936658ba844268783ef
+  data.tar.gz: 4e36cb8eea3d23a338e558784ec8c72bb4bdfecc8c981d094c72784b0f88181e
+SHA512:
+  metadata.gz: 8fb29df856db1970afb0b1b24c11316501f5edf6e9962f244d31af0dd13d150eaf02c1082e84c931d2ac77798dc2239b063092b4cda0dbbdc6d6fd28d3240df4
+  data.tar.gz: 2f0cc430e55895e929ca985723c0f8aa7b1be6549af05184f71f171b122afeda65ec47529c249aea93f7acf0d3ccede50405bcbc841af05ad00c62155a39d093

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright zhandao
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,480 @@
+# ActionSpec [WIP]
+
+Concise and Powerful API Documentation Solution for Rails.
+
+<img src=".github/assets/action_spec.jpg" />
+
+- 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.
+
+## Overview
+
+ActionSpec keeps API request contracts close to controller actions. It gives you a readable DSL for declaring request and response shapes, and runtime helpers for validation and type coercion.
+
+## Current Scope
+
+- A controller-friendly DSL for declaring request and response contracts
+- Runtime validation and type coercion based on that DSL
+- `px`, a validated hash built from the declared contract
+
+OpenAPI generation is planned, but not implemented yet.
+
+### Quick Start
+
+```ruby
+class UsersController < ApplicationController
+  before_action :validate_and_coerce_params!, only: :create
+
+  doc {
+    header :Authorization, String
+    path :account_id, Integer
+    query :locale, String, default: "zh-CN"
+    query :page, Integer, default: -> { 1 }
+
+    json data: {
+      name!: String,
+      age: Integer,
+      birthday: Date,
+      admin: { type: :boolean, default: false },
+      tags: [String],
+      profile: {
+        nickname!: String
+      }
+    }
+
+    response 200, desc: "success"
+  }
+  def create
+    User.create!(
+      account_id: px[:account_id],
+      name: px[:name],
+      birthday: px[:birthday],
+      admin: px[:admin]
+    )
+  end
+end
+```
+
+## Installation
+
+```ruby
+# Gemfile
+gem "action_spec"
+```
+
+Then run:
+
+```bash
+$ bundle
+```
+
+## Usage
+
+### How To Bind `doc`
+
+Default form, with action inferred from the next instance method:
+
+```ruby
+doc {
+  json data: { name!: String }
+}
+def create
+end
+```
+
+You can still provide a summary in the default form:
+
+```ruby
+doc("Create user") {
+  json data: { name!: String }
+}
+def create
+end
+```
+
+You can also bind it explicitly when you want the action name declared in place:
+
+```ruby
+doc(:create, "Create user") {
+  json data: { name!: String }
+}
+def create
+end
+```
+
+### Shared Declarations With `doc_dry`
+
+```ruby
+class ApplicationController < ActionController::API
+  doc_dry %i[show update destroy] do
+    path! :id, Integer
+  end
+
+  doc_dry :index do
+    query :page, Integer, default: 1
+    query :per, Integer, default: 20
+  end
+end
+```
+
+All matching dry blocks are applied before the action-specific `doc`.
+
+### DSL Reference
+
+ActionSpec keeps the request DSL close to `zero-rails_openapi`.
+
+#### Parameter Locations
+
+Single-parameter forms:
+
+```ruby
+header  :Authorization, String
+header! :Authorization, String
+
+path  :id, Integer
+path! :id, Integer
+
+query  :page, Integer
+query! :page, Integer
+
+cookie  :remember_token, String
+cookie! :remember_token, String
+```
+
+Bang methods mark the field as required. For example, `query! :page, Integer` means the request must include `page`.
+
+Batch declaration forms:
+
+```ruby
+in_header(
+  Authorization: String
+)
+
+in_path!(
+  id: Integer
+)
+
+in_query(
+  page: Integer,
+  per: { type: Integer, default: 20 },
+  locale: String
+)
+
+in_cookie(
+  remember_token: String
+)
+
+in_query!(
+  user_id: Integer,
+  token: String
+)
+```
+
+#### Request Bodies
+
+General form:
+
+```ruby
+body :json, data: { name!: String, age: Integer }
+```
+
+Convenience helpers:
+
+```ruby
+json data: { name!: String }
+
+json! data: { name!: String }
+
+form data: { file!: File, position: String }
+
+form! data: { file!: File }
+```
+
+Single multipart field helper:
+
+```ruby
+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.
+
+#### Response Metadata
+
+```ruby
+response 200, desc: "success"
+response 422, "validation failed"
+resp 400, "bad request"
+error 401, "unauthorized"
+```
+
+Response declarations are stored as metadata now. They are not yet used to render responses automatically.
+
+### Schema Writing
+
+#### Required Fields
+
+Use `!` in either place:
+
+```ruby
+query! :page, Integer
+
+json data: {
+  name!: String,
+  profile: {
+    nickname!: String
+  }
+}
+```
+
+Meaning of `!`:
+
+- `query!`, `path!`, `header!`, `cookie!` mark the parameter itself as required
+- 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
+
+Scalar types currently supported by validation/coercion:
+
+- `String`
+- `Integer`
+- `Float`
+- `BigDecimal`
+- `:boolean`
+- host-defined `Boolean` constant, if the host app already defines one
+- `Date`
+- `DateTime`
+- `Time`
+- `File`
+- `Object`
+
+Nested forms:
+
+```ruby
+json data: {
+  tags: [String],
+  profile: {
+    nickname!: String
+  },
+  settings: { type: Object }
+}
+```
+
+#### 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
+
+These options are currently used by the validator:
+
+```ruby
+query :page, Integer, default: 1
+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/
+```
+
+These options are currently accepted as metadata, mainly for future OpenAPI work, but are not yet used by the runtime validator:
+
+- `desc`
+- `example`
+- `examples`
+- `allow_nil`
+- `allow_blank`
+
+### Validation Flow
+
+#### `validate_params!`
+
+Validates using the DSL, but keeps raw values in `px`.
+
+```ruby
+before_action :validate_params!
+```
+
+Example:
+
+- request query param `"page" => "2"`
+- DSL says `query :page, Integer`
+- result: `px[:page] == "2"`
+
+#### `validate_and_coerce_params!`
+
+Validates and coerces values before exposing them on `px`.
+
+```ruby
+before_action :validate_and_coerce_params!
+```
+
+Example:
+
+- request query param `"page" => "2"`
+- DSL says `query :page, Integer`
+- result: `px[:page] == 2`
+
+### Reading Validated Values With `px`
+
+`px` is a hash.
+
+```ruby
+px[:id]
+px[:page]
+px[:profile][:nickname]
+px.to_h
+```
+
+It also includes grouped buckets:
+
+```ruby
+px[:path]
+px[:query]
+px[:body]
+px[:headers]
+px[:cookies]
+```
+
+Notes:
+
+- root values from path/query/body are also flattened into `px[:name]`
+- 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"]
+```
+
+- original `params` are not mutated
+
+### Errors
+
+Validation errors are stored in `ActiveModel::Errors`.
+
+If invalid parameters are not rescued, ActionSpec raises `ActionSpec::InvalidParameters`:
+
+```ruby
+begin
+  validate_and_coerce_params!
+rescue ActionSpec::InvalidParameters => error
+  error.errors.full_messages
+end
+```
+
+The exception also keeps the full validation result on `error.result` and `error.parameters`.
+
+### 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
+```
+
+The default JSON response is:
+
+```json
+{
+  "errors": {
+    "page": ["Page is required"]
+  }
+}
+```
+
+### Configuration
+
+```ruby
+ActionSpec.configure do |config|
+  config.rescue_invalid_parameters = true
+  config.invalid_parameters_status = :bad_request
+
+  config.error_messages[:invalid_type] = ->(_attribute, options) do
+    "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:
+
+- `invalid_parameters_exception_class`
+  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.
+
+### I18n
+
+ActionSpec loads its own locale files and uses `ActiveModel::Errors`, so you can override both messages and attribute names:
+
+```yml
+en:
+  activemodel:
+    attributes:
+      action_spec/parameters:
+        "profile.nickname": "Profile nickname"
+    errors:
+      messages:
+        required: "is required"
+        invalid_type: "must be a valid %{expected}"
+```
+
+You can also override messages per error type or per attribute in Ruby:
+
+```ruby
+ActionSpec.configure do |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
+
+- OpenAPI document generation
+- automatic response rendering from `response`
+- reusable schema/components system from `zero-rails_openapi`
+- runtime behavior for `allow_nil` / `allow_blank`
+
+## Contributing
+.
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,3 @@
+require "bundler/setup"
+
+require "bundler/gem_tasks"

data/config/locales/en.yml

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

data/config/locales/zh.yml

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

data/lib/action_spec/configuration.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module ActionSpec
+  class Configuration
+    attr_accessor :invalid_parameters_exception_class, :invalid_parameters_status, :rescue_invalid_parameters,
+                  :invalid_parameters_renderer
+    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
+      @error_messages = ActiveSupport::HashWithIndifferentAccess.new
+    end
+
+    def error_messages=(value)
+      @error_messages = ActiveSupport::HashWithIndifferentAccess.new(value)
+    end
+
+    def message_for(attribute, type, options = {})
+      configured = error_messages.dig(attribute.to_sym, type.to_sym) || error_messages[type.to_sym]
+      return if configured.blank?
+
+      configured.respond_to?(:call) ? configured.call(attribute.to_sym, options) : configured
+    end
+
+    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.error_messages = error_messages.deep_dup
+      end
+    end
+  end
+end

data/lib/action_spec/doc/dsl.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module ActionSpec
+  module Doc
+    class Dsl
+      PARAM_LOCATIONS = %i[header path query cookie].freeze
+
+      def initialize(endpoint)
+        @endpoint = endpoint
+      end
+
+      PARAM_LOCATIONS.each do |location_name|
+        define_method(location_name) do |name, type = String, **options|
+          add_param(location_name, name, type, required: false, **options)
+        end
+
+        define_method("#{location_name}!") do |name, type = String, **options|
+          add_param(location_name, name, type, required: true, **options)
+        end
+
+        define_method("in_#{location_name}") do |params|
+          add_many(location_name, params, required: false)
+        end
+
+        define_method("in_#{location_name}!") do |params|
+          add_many(location_name, params, required: true)
+        end
+      end
+
+      def body(media_type, data: {}, **)
+        add_body(media_type, data)
+      end
+
+      def body!(media_type, data: {}, **)
+        add_body(media_type, data)
+      end
+
+      def json(data:, **options)
+        body(:json, data:, **options)
+      end
+
+      def json!(data:, **options)
+        body!(:json, data:, **options)
+      end
+
+      def form(data:, **options)
+        body(:form, data:, **options)
+      end
+
+      def form!(data:, **options)
+        body!(:form, data:, **options)
+      end
+
+      def data(name, type = String, **options)
+        add_body(:form, { name => options.merge(type:) })
+      end
+
+      def response(code, description = nil, media_type = nil, desc: nil, **options)
+        endpoint.add_response(
+          code,
+          Response.new(
+            code:,
+            description: description || desc.to_s,
+            media_type:,
+            options:
+          )
+        )
+      end
+
+      alias resp response
+      alias error response
+
+      private
+
+        attr_reader :endpoint
+
+        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:))
+        end
+
+        def add_many(location_name, params, required:)
+          params.each_pair do |name, definition|
+            if definition.is_a?(Hash) && !definition.key?(:type) && !definition.key?("type")
+              schema_options = definition.symbolize_keys
+              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))
+                )
+              else
+                add_param(location_name, name, String, required:, **definition)
+              end
+            elsif definition.is_a?(Hash)
+              add_param(location_name, name, definition[:type] || definition["type"] || String, required:, **definition.symbolize_keys.except(:type))
+            else
+              add_param(location_name, name, definition, required:)
+            end
+          end
+        end
+
+        def add_body(media_type, definition)
+          ActionSpec::Schema.build_fields(definition).each_value do |field|
+            endpoint.request.add_body(media_type, field)
+          end
+        end
+    end
+  end
+end