action_spec 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 02c55ca1816d1b61ad17a4a735c1704bb887cc4f67d842a7ed351641c47e93d8
-  data.tar.gz: a148b5f034a92b4f6648c3deb5e29aa997588e6162cd761e3586e9840d6b0fa2
+  metadata.gz: 432c84ac7303d7194f5617f2fe724bdb2d332662eb543a0545712731cac767dc
+  data.tar.gz: 90343cbda95d9a89452aabf86da6731606d2404a4c2bcd0a9358b48f705bd6cb
 SHA512:
-  metadata.gz: 1eb2aa363f52d5800497364315168186b3fb04fc0fc1541ebe2075a73284585a5302b68f48183f5163451607f53bddc42474a988a6549dcb4daf7849bd2bf9aa
-  data.tar.gz: 985e5bd7551b4f6bd9919209137c90cae86a3a2720113dacb01e421849fca4e16a602550fb833a920d703f997c97a2b8b87c49ceda5ce4ecefa9bfea1a641988
+  metadata.gz: 631a11eea99a092b2c104ff3934fcddd1777f8a2346468ef91170ff1bc5acea9844002b438b4ec668a5a20f7a97d58c69bdf8f99482b1b757e4ccf01fadf119c
+  data.tar.gz: 886a2975a48967efcf844c4577f05c2ebbb4cd8ed2d6c883e80c6830b1388f57b38b9f6e202376b01a71d1109ec75869d20ab143950d60cb5638e98e4b111c02

data/README.md

@@ -1,6 +1,6 @@
-# ActionSpec [WIP]
+# ActionSpec
 
-Concise and Powerful API Documentation Solution for Rails.
+Concise and Powerful API Documentation Solution for Rails. [中文](README_zh.md)
 
 <img src=".github/assets/action_spec.jpg" />
 
@@ -10,27 +10,30 @@ Concise and Powerful API Documentation Solution for Rails.
 
 ## Table Of Contents
 
-- [OpenAPI Generation](#openapi-generation)
-- [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)
-  - [Field Types](#field-types)
-  - [Field Options](#field-options)
-  - [Schemas From ActiveRecord](#schemas-from-activerecord)
-  - [Type And Boundary Matrix](#type-and-boundary-matrix)
-- [Parameter Validation And Type Coercion](#parameter-validation-and-type-coercion)
-  - [Validation Flow](#validation-flow)
-  - [Reading Processed Values With `px`](#reading-processed-values-with-px)
-  - [Errors](#errors)
-- [Configuration And I18n](#configuration-and-i18n)
-  - [Configuration](#configuration)
-  - [I18n](#i18n)
-- [AI Generation Style Guide](#ai-generation-style-guide)
+1. [OpenAPI Generation](#openapi-generation)
+2. [Doc DSL](#doc-dsl)
+   1. [`doc`](#doc)
+   2. [`doc_dry`](#doc_dry)
+   3. [DSL Inside `doc`](#dsl-inside-doc)
+      1. [Parameter](#parameter)
+      2. [request body](#request-body)
+      3. [`openapi false`](#openapi-false)
+      4. [Scope](#scope)
+      5. [Response](#response)
+3. [Schemas](#schemas)
+   1. [Declare A Required Field](#declare-a-required-field)
+   2. [Field Types](#field-types)
+   3. [Field Options](#field-options)
+   4. [Schemas From ActiveRecord](#schemas-from-activerecord)
+   5. [Type And Boundary Matrix](#type-and-boundary-matrix)
+4. [Parameter Validation And Type Coercion](#parameter-validation-and-type-coercion)
+   1. [Validation Flow](#validation-flow)
+   2. [Reading Processed Values With `px`](#reading-processed-values-with-px)
+   3. [Errors](#errors)
+5. [Configuration And I18n](#configuration-and-i18n)
+   1. [Configuration](#configuration)
+   2. [I18n](#i18n)
+6. [AI Generation Style Guide](#ai-generation-style-guide)
 
 ## Example
 
@@ -59,10 +62,8 @@ class UsersController < ApplicationController
   }
   def create
     User.create!(
-      account_id: px[:account_id],
-      name: px[:name],
-      birthday: px[:birthday],
-      admin: px[:admin]
+      account_id: px[:account_id], name: px[:name],
+      **px.slice(:birthday, :admin, :profile)
     )
   end
 end
@@ -95,7 +96,7 @@ By default, this writes to:
 docs/openapi.yml
 ```
 
-For one-off runs, environment variables can override the default output path and document metadata:
+Environment variables can override the default output path and document metadata:
 
 ```bash
 bin/rails action_spec:gen \
@@ -149,6 +150,18 @@ def create
 end
 ```
 
+Override the default OpenAPI tag with `tag:`. By default, the tag comes from the routed `controller_path`:
+
+```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`.
+
 ### `doc_dry`
 
 ```ruby
@@ -166,31 +179,7 @@ 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
+### DSL Inside `doc`
 
 #### Parameter
 
@@ -208,7 +197,16 @@ 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`.
+Bang methods mark the field as required. For example, `query! :page, Integer` means the request must include `page`, and the value must not be `nil`. Blank values are still allowed unless you set `blank: false`.
+
+If you prefer not to use bang methods, you can also write `required: true`:
+
+```ruby
+query :page, Integer, required: true
+json data: {
+  title: { type: String, required: true }
+}
+```
 
 Batch declaration forms:
 
@@ -249,11 +247,9 @@ Convenience helpers:
 
 ```ruby
 json data: { name!: String }
-
 json! data: { name!: String }
 
 form data: { file!: File, position: String }
-
 form! data: { file!: File }
 ```
 
@@ -263,16 +259,23 @@ Single multipart field helper:
 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.
+Notes:
+
+1. When multiple `body/body!`, `json/json!`, or `form/form!` declarations are used:
+   - declarations with the same media type are merged
+   - if multiple media types are declared, the generated OpenAPI document will emit multiple media types
+   - field validation and coercion do not distinguish between media types, and always read values from Rails `params`
 
-#### OpenAPI
+`body!`, `json!`, and `form!` make the root request body required at runtime. You can also write `required: true` on `body`, `json`, or `form` if you prefer not to use bang methods.
+
+#### `openapi false`
+
+You can also opt an action out of OpenAPI generation from either `doc` or `doc_dry`:
 
 ```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:
@@ -283,6 +286,7 @@ doc {
     query :user_id, Integer
     form data: { name: String }
   }
+  form data: { not_in_scope: String }
 }
 ```
 
@@ -297,11 +301,27 @@ px.scope[:user] # => { user_id: 1, name: "Tom" }
 ```ruby
 response 200, desc: "success"
 response 422, "validation failed"
-resp 400, "bad request"
+response 200, :json, data: { code!: Integer, result: Object }
+
 error 401, "unauthorized"
+error 503, { code!: Integer, message!: String } # error data schema
+error 503, { code: 1000, message: "invalid params" } # unnamed error example
+error 503, invalid_params: { code: 1000, message: "invalid params" } # named error example
+# declare multiple named examples in batch
+errors 503, {
+  invalid_params: { code: 1000, message: "invalid params" },
+  network_error: { code: 1001, message: "network error" }
+}
+errors 503, network_error: { code: 1001 }, upstream_timeout: { code: 1002 } # braces are also optional
+
 ```
 
-Response declarations are stored as metadata now. They are not yet used to render responses automatically.
+Response declarations are stored as metadata and are emitted in OpenAPI. They do not render responses automatically at runtime.
+
+Notes:
+
+1. `response`, `error`, and `errors` default `media_type` to `:json` and this default is configurable.
+2. If examples are declared without an explicit schema, ActionSpec infers the response schema from the example payloads for OpenAPI generation.
 
 ## Schemas
 
@@ -324,7 +344,11 @@ 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
+- `body!`, `json!`, and `form!` mark the root request body as required
+
+You can also use `required: true` instead of bang syntax for parameters, nested fields, and the root request body.
+
+`required` in ActionSpec means "present and not `nil`". It does not reject blank strings by itself. If you want to reject blank values, use `blank: false` or `allow_blank: false`.
 
 #### Field Types
 
@@ -356,26 +380,31 @@ json data: {
 
 #### Field 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/
+query :title, String, blank: false # or allow_blank: false
+
+query :nickname, String, transform: :downcase
+query :page, Integer, transform: -> { it + 1 }, px: :page_number
+query :request_id, String, px_key: :trace_id
 ```
 
-These options are currently used by OpenAPI generation, but are not yet used by the runtime validator:
+Notes:
+
+- `transform` accepts a `Symbol` or a `Proc` and runs **after coercion**, before the value is written into `px`
+- `px` and `px_key` customize the key name written into `px`; `px` is the short form of `px_key`
 
-- `desc`
-- `example`
-- `examples`
+These options are used by OpenAPI generation:
 
-These options are not yet used by either the runtime validator or OpenAPI generation:
+```ruby
+query :page, Integer, desc: "page number", example: 1, examples: [1, 2, 3]
+```
 
-- `allow_nil`
-- `allow_blank`
+If an OpenAPI-facing option such as `default` cannot be converted into YAML, for example `default: -> { ... }`, it will be omitted from the generated OpenAPI document.
 
 #### Schemas From ActiveRecord
 
@@ -484,6 +513,7 @@ This hook also skips actions without a matching `doc`, so it is safe to declare
 ### 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
@@ -555,6 +585,7 @@ ActionSpec.configure { |config|
   config.open_api_title = "My API"
   config.open_api_version = "2026.03"
   config.open_api_server_url = "https://api.example.com"
+  config.default_response_media_type = :json
 
   config.error_messages[:invalid_type] = ->(_attribute, options) {
     "should be coercible to #{options.fetch(:expected)}"
@@ -564,29 +595,13 @@ ActionSpec.configure { |config|
 
 Available config keys:
 
-- `invalid_parameters_exception_class`
-  Default: `ActionSpec::InvalidParameters`.
-  Controls which exception class is raised when validation fails.
-
-- `error_messages`
-  Default: `{}`.
-  Lets you override error messages by error type, or by attribute plus error type.
-
-- `open_api_output`
-  Default: `"docs/openapi.yml"`.
-  Controls where `bin/rails action_spec:gen` writes the generated OpenAPI document.
-
-- `open_api_title`
-  Default: `nil`.
-  Sets the default OpenAPI `info.title` used by `bin/rails action_spec:gen`.
-
-- `open_api_version`
-  Default: `nil`.
-  Sets the default OpenAPI `info.version` used by `bin/rails action_spec:gen`.
-
-- `open_api_server_url`
-  Default: `nil`.
-  Sets the default server URL emitted in the generated OpenAPI document.
+- `invalid_parameters_exception_class`: Default `ActionSpec::InvalidParameters`; controls which exception class is raised when validation fails.
+- `error_messages`: Default `{}`; lets you override error messages by error type, or by attribute plus error type.
+- `open_api_output`: Default `"docs/openapi.yml"`; controls where `bin/rails action_spec:gen` writes the generated OpenAPI document.
+- `open_api_title`: Default `nil`; sets the default OpenAPI `info.title` used by `bin/rails action_spec:gen`.
+- `open_api_version`: Default `nil`; sets the default OpenAPI `info.version` used by `bin/rails action_spec:gen`.
+- `open_api_server_url`: Default `nil`; sets the default server URL emitted in the generated OpenAPI document.
+- `default_response_media_type`: Default `:json`; sets the default response media type used by `response`, `error`, and `errors` when no media type is passed explicitly.
 
 ### I18n
 
@@ -625,7 +640,7 @@ When using AI tools to generate Rails controller code, and the change involves p
 - when a batch has 3 fields or fewer and does not contain nested hashes, prefer a single-line style, for example:
   - `json data: { type: String, required: true }`
   - `in_query(name: String, value: String)` (prefer `in_xxx(...)` batch declarations over multiple `xx` DSL lines when possible)
-- use `doc_dry`, `scope`, and `px.slice` to reduce repetition in controllers
+- use `doc_dry`, `scope`, and `transform`、`px(px_key)`、`px.slice` to keep controller concise
 - when request parameters match model declarations, prefer `.schemas` to keep `doc` concise
 
 ## What Is Not Implemented Yet
@@ -636,7 +651,6 @@ When using AI tools to generate Rails controller code, and the change involves p
 - 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
@@ -647,7 +661,7 @@ When using AI tools to generate Rails controller code, and the change involves p
 - 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`
+- richer schema keywords beyond the current subset, including object-level constraints, and composition keywords such as `oneOf`, `anyOf`, `allOf`, and `not`
 
 ## Contributing
 

data/lib/action_spec/configuration.rb

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

data/lib/action_spec/doc/dsl.rb

@@ -28,12 +28,12 @@ module ActionSpec
         end
       end
 
-      def body(media_type, data: {}, **)
-        add_body(media_type, data)
+      def body(media_type, data: {}, required: false, **)
+        add_body(media_type, data, required:)
       end
 
       def body!(media_type, data: {}, **)
-        add_body(media_type, data)
+        add_body(media_type, data, required: true)
       end
 
       def json(data:, **options)
@@ -67,57 +67,85 @@ module ActionSpec
         endpoint.options[:openapi] = enabled
       end
 
-      def response(code, description = nil, media_type = nil, desc: nil, **options)
+      RESPONSE_MEDIA_TYPES = %i[json form].freeze
+
+      def response(code, description = nil, media_type = nil, desc: nil, data: nil, example: nil, examples: nil, **options)
+        description, media_type = normalize_response_arguments(description, media_type)
+        schema, example, examples = normalize_response_body(description, data:, example:, examples:, options:)
         endpoint.add_response(
           code,
           Response.new(
             code:,
-            description: description || desc.to_s,
-            media_type:,
+            description: resolved_description(description, desc),
+            media_type: media_type || ActionSpec.config.default_response_media_type,
+            schema:,
+            example:,
+            examples:,
             options:
           )
         )
       end
 
-      alias resp response
-      alias error response
+      def error(code, description = nil, media_type = nil, desc: nil, **options)
+        response(code, description, media_type, desc: desc || "Error", **options)
+      end
+
+      def errors(code, examples = nil, media_type = nil, desc: "Error", **options)
+        response(code, nil, media_type, desc:, examples: examples || options, **options.except(*Array((examples || options).keys)))
+      end
 
       private
 
         attr_reader :endpoint
         attr_reader :scopes
 
+        def normalize_response_arguments(description, media_type)
+          return [nil, description] if media_type.nil? && response_media_type?(description)
+
+          [description, media_type]
+        end
+
+        def response_media_type?(value)
+          value.is_a?(Symbol) && RESPONSE_MEDIA_TYPES.include?(value)
+        end
+
+        def normalize_response_body(description, data:, example:, examples:, options:)
+          return [data && ActionSpec::Schema.from_definition(data), example, examples] if data || example || examples
+          return [nil, nil, options.presence] if options.present?
+          return [nil, nil, nil] if description.is_a?(String) || description.nil?
+
+          parsed_schema = ActionSpec::Schema.schema_definition?(description) ? ActionSpec::Schema.from_definition(description) : nil
+          return [parsed_schema, nil, nil] if parsed_schema
+
+          [nil, description, options.presence]
+        end
+
+        def resolved_description(description, desc)
+          return description if description.is_a?(String)
+          return desc if desc.present?
+
+          nil
+        end
+
         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:, scopes: scopes.dup))
+          required ||= options.delete(:required) == true
+          endpoint.request.add_param(
+            location_name,
+            ActionSpec::Schema.build_field(name, options.merge(type:), required:, scopes: scopes.dup)
+          )
         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),
-                    scopes: scopes.dup
-                  )
-                )
-              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
+            endpoint.request.add_param(
+              location_name,
+              ActionSpec::Schema.build_field(name, definition, required:, scopes: scopes.dup)
+            )
           end
         end
 
-        def add_body(media_type, definition)
+        def add_body(media_type, definition, required:)
+          endpoint.request.require_body! if required
           ActionSpec::Schema.build_fields(definition, scopes: scopes.dup).each_value do |field|
             endpoint.request.add_body(media_type, field)
           end

data/lib/action_spec/doc/endpoint.rb

@@ -23,7 +23,8 @@ module ActionSpec
       end
 
       def add_response(code, response)
-        @responses[code.to_s] = response
+        existing = @responses[code.to_s]
+        @responses[code.to_s] = existing ? existing.merge(response) : response
       end
 
       def copy
@@ -46,6 +47,7 @@ module ActionSpec
         @cookie = Location.new(:cookie)
         @body = Location.new(:body)
         @body_media_types = {}
+        @body_required = false
       end
 
       def location(name)
@@ -61,6 +63,14 @@ module ActionSpec
         (@body_media_types[media_type.to_sym] ||= Location.new(media_type.to_sym)).add(field.copy)
       end
 
+      def require_body!
+        @body_required = true
+      end
+
+      def body_required?
+        @body_required
+      end
+
       def replace_with(other)
         @header = other.header
         @path = other.path
@@ -68,6 +78,7 @@ module ActionSpec
         @cookie = other.cookie
         @body = other.body
         @body_media_types = other.body_media_types
+        @body_required = other.body_required?
       end
 
       def copy
@@ -81,6 +92,7 @@ module ActionSpec
             :@body_media_types,
             body_media_types.transform_values(&:copy)
           )
+          request.instance_variable_set(:@body_required, body_required?)
         end
       end
     end
@@ -123,18 +135,87 @@ module ActionSpec
     end
 
     class Response
-      attr_reader :code, :description, :media_type, :options
+      attr_reader :code, :description, :media_types, :options
 
-      def initialize(code:, description:, media_type:, options:)
+      def initialize(code:, description:, media_type:, schema: nil, example: nil, examples: nil, options:)
         @code = code.to_s
         @description = description
-        @media_type = media_type
-        @options = options
+        @media_types = ActiveSupport::OrderedHash.new
+        @options = options.deep_dup
+        merge_media_type!(media_type || :json, schema:, example:, examples:, initialize: true)
+      end
+
+      def merge(other)
+        copy.tap do |merged|
+          merged.instance_variable_set(:@description, other.description.presence || description)
+          merged.instance_variable_set(:@options, options.deep_dup.merge(other.options.deep_dup))
+          other.media_types.each do |media_type, content|
+            merged.send(:merge_media_type!, media_type, **merged.send(:copy_content, content))
+          end
+        end
       end
 
       def copy
-        self.class.new(code:, description:, media_type:, options: options.deep_dup)
+        self.class.new(
+          code:,
+          description:,
+          media_type: nil,
+          schema: nil,
+          example: nil,
+          examples: nil,
+          options: options.deep_dup
+        ).tap do |response|
+          response.instance_variable_set(
+            :@media_types,
+            media_types.each_with_object(ActiveSupport::OrderedHash.new) do |(media_type, content), hash|
+              hash[media_type] = copy_content(content)
+            end
+          )
+        end
       end
+
+      private
+
+        def merge_media_type!(media_type, schema:, example:, examples:, initialize: false)
+          content = (@media_types[media_type.to_sym] ||= {
+            schema: nil,
+            example: nil,
+            examples: ActiveSupport::OrderedHash.new
+          })
+          content[:schema] = schema || content[:schema]
+
+          if examples.present?
+            convert_example_into_default_example!(content)
+            content[:examples].merge!(normalize_examples(examples))
+          elsif !example.nil?
+            if content[:examples].present? && !initialize
+              content[:examples]["default"] ||= example
+            else
+              content[:example] = example
+            end
+          end
+        end
+
+        def convert_example_into_default_example!(content)
+          return if content[:example].nil?
+
+          content[:examples]["default"] ||= content[:example]
+          content[:example] = nil
+        end
+
+        def normalize_examples(examples)
+          examples.each_with_object(ActiveSupport::OrderedHash.new) do |(name, value), hash|
+            hash[name.to_s] = value
+          end
+        end
+
+        def copy_content(content)
+          {
+            schema: content[:schema]&.copy,
+            example: content[:example].deep_dup,
+            examples: content[:examples].deep_dup
+          }
+        end
     end
   end
 end

data/lib/action_spec/open_api/operation.rb

@@ -52,7 +52,7 @@ module ActionSpec
           return { "200" => { "description" => "OK" } } if endpoint.responses.empty?
 
           endpoint.responses.each_with_object(ActiveSupport::OrderedHash.new) do |(code, response), hash|
-            hash[code] = { "description" => response.description.presence || "OK" }
+            hash[code] = schema.response(response)
           end
         end
     end

data/lib/action_spec/open_api/schema.rb

@@ -36,7 +36,16 @@ module ActionSpec
         end
         return if content.empty?
 
-        { "content" => content }
+        { "content" => content }.tap do |body|
+          body["required"] = true if request.body_required?
+        end
+      end
+
+      def response(response)
+        {
+          "description" => response.description.presence || "OK",
+          "content" => response_content(response).presence
+        }.compact
       end
 
       def schema_for(schema)
@@ -50,6 +59,29 @@ module ActionSpec
 
       private
 
+        def response_content(response)
+          response.media_types.each_with_object(ActiveSupport::OrderedHash.new) do |(media_type, content), hash|
+            normalized = response_media_type_content(content)
+            next if normalized.blank?
+
+            hash[MEDIA_TYPE_MAP.fetch(media_type, media_type.to_s)] = normalized
+          end
+        end
+
+        def response_media_type_content(content)
+          {}.tap do |definition|
+            if (schema = content[:schema] || infer_schema_from_examples(content)).present?
+              definition["schema"] = schema_for(schema)
+            end
+
+            if (examples = normalize_response_examples(content[:examples])).present?
+              definition["examples"] = examples
+            elsif (example = normalize_response_example(content[:example])).present?
+              definition["example"] = example
+            end
+          end.presence
+        end
+
         def parameter_name(field, location)
           return field.name.to_s if location != :header
 
@@ -198,6 +230,79 @@ module ActionSpec
         def invalid_openapi_literal
           @invalid_openapi_literal ||= Object.new.freeze
         end
+
+        def normalize_response_example(example)
+          normalized = openapi_literal(example)
+          return if normalized.nil? || normalized.equal?(invalid_openapi_literal)
+
+          normalized
+        end
+
+        def normalize_response_examples(examples)
+          return if examples.blank?
+
+          examples.each_with_object(ActiveSupport::OrderedHash.new) do |(name, value), hash|
+            normalized = openapi_literal(value)
+            next if normalized.nil? || normalized.equal?(invalid_openapi_literal)
+
+            hash[name.to_s] = { "value" => normalized }
+          end.presence
+        end
+
+        def infer_schema_from_examples(content)
+          values =
+            if content[:examples].present?
+              content[:examples].values
+            elsif !content[:example].nil?
+              [content[:example]]
+            else
+              []
+            end
+          return if values.blank?
+
+          definition = infer_definition(values)
+          return if definition.blank?
+
+          ActionSpec::Schema.from_definition(definition)
+        end
+
+        def infer_definition(values)
+          values = Array(values)
+          present_values = values.compact
+          return if present_values.empty?
+
+          return infer_object_definition(present_values) if present_values.all? { |value| value.is_a?(Hash) }
+          return infer_array_definition(present_values) if present_values.all? { |value| value.is_a?(Array) }
+
+          infer_scalar_definition(present_values)
+        end
+
+        def infer_object_definition(values)
+          keys = values.flat_map(&:keys).map(&:to_s).uniq
+          keys.each_with_object(ActiveSupport::OrderedHash.new) do |key, definition|
+            child_values = values.select { |value| value.key?(key) || value.key?(key.to_sym) }.map { |value| value[key] || value[key.to_sym] }
+            child_definition = infer_definition(child_values)
+            next if child_definition.blank?
+
+            name = values.all? { |value| value.key?(key) || value.key?(key.to_sym) } ? :"#{key}!" : key.to_sym
+            definition[name] = child_definition
+          end
+        end
+
+        def infer_array_definition(values)
+          flattened = values.flatten(1)
+          item_definition = infer_definition(flattened)
+          item_definition ? [item_definition] : []
+        end
+
+        def infer_scalar_definition(values)
+          return Integer if values.all? { |value| value.is_a?(Integer) }
+          return Float if values.all? { |value| value.is_a?(Numeric) }
+          return :boolean if values.all? { |value| value == true || value == false }
+          return String if values.all? { |value| value.is_a?(String) }
+
+          String
+        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:, length:, allow_nil:, allow_blank:, desc: description, example:, examples:)
+        self.class.new(item.copy, default:, enum:, range:, pattern:, length:, 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, :length, :allow_nil, :allow_blank, :description, :example, :examples
+      attr_reader :default, :enum, :range, :pattern, :length, :blank, :description, :example, :examples
 
       def initialize(options = {})
         options = options.symbolize_keys
@@ -12,17 +12,22 @@ module ActionSpec
         @range = options[:range]
         @pattern = options[:pattern]
         @length = options[:length]
-        @allow_nil = options[:allow_nil]
-        @allow_blank = options[:allow_blank]
+        @blank = options.key?(:blank) ? options[:blank] : options.fetch(:allow_blank, true)
         @description = options[:desc] || options[:description]
         @example = options[:example]
         @examples = options[:examples]
       end
 
-      def materialize_missing(_context:, _coerce:, _result:, _path:)
+      alias allow_blank blank
+
+      def materialize_missing(context:, coerce:, result:, path:)
         Schema::Missing
       end
 
+      def blank_allowed?
+        blank != false
+      end
+
       def validate_constraints(value, result:, path:)
         return if value.nil?
 

data/lib/action_spec/schema/field.rb

@@ -3,12 +3,14 @@
 module ActionSpec
   module Schema
     class Field
-      attr_reader :name, :schema, :scopes
+      attr_reader :name, :schema, :transform, :px_key, :scopes
 
-      def initialize(name:, required:, schema:, scopes: [])
+      def initialize(name:, required:, schema:, transform: nil, px_key: nil, scopes: [])
         @name = name.to_sym
         @required = required
         @schema = schema
+        @transform = transform
+        @px_key = px_key&.to_sym
         @scopes = Array(scopes).map(&:to_sym).freeze
       end
 
@@ -20,9 +22,48 @@ module ActionSpec
         schema.default
       end
 
+      def output_name
+        px_key || name
+      end
+
+      def transform_value(value, context: nil)
+        return value if transform.nil? || value.equal?(ActionSpec::Schema::Missing)
+
+        case transform
+        when Symbol, String then apply_symbol_transform(value, context:)
+        when Proc then apply_proc_transform(value, context:)
+        else value
+        end
+      end
+
       def copy
-        self.class.new(name:, required: required?, schema: schema.copy, scopes:)
+        self.class.new(name:, required: required?, schema: schema.copy, transform:, px_key:, scopes:)
       end
+
+      private
+
+        def apply_symbol_transform(value, context:)
+          symbol = transform.to_sym
+          return value.public_send(symbol) if value.respond_to?(symbol)
+          return invoke_context_transform(context, symbol, value) if context&.respond_to?(symbol, true)
+
+          value
+        end
+
+        def apply_proc_transform(value, context:)
+          return context.instance_exec(&transform) if context && transform.arity.zero?
+          return context.instance_exec(value, &transform) if context && (transform.arity == 1 || transform.arity.negative?)
+          return transform.call if transform.arity.zero?
+
+          transform.call(value)
+        end
+
+        def invoke_context_transform(context, symbol, value)
+          method = context.method(symbol)
+          return context.public_send(symbol) if method.arity.zero?
+
+          context.public_send(symbol, value)
+        end
     end
   end
 end

data/lib/action_spec/schema/object_of.rb

@@ -24,7 +24,7 @@ module ActionSpec
             result:,
             path:
           ).resolve
-          output[field.name] = resolved unless resolved.equal?(Schema::Missing)
+          output[field.output_name] = resolved unless resolved.equal?(Schema::Missing)
         end
         output.presence || (source.present? ? output : Schema::Missing)
       end
@@ -34,7 +34,7 @@ module ActionSpec
       end
 
       def copy
-        self.class.new(fields.transform_values(&:copy), default:, enum:, range:, pattern:, length:, allow_nil:, allow_blank:, desc: description, example:, examples:)
+        self.class.new(fields.transform_values(&:copy), default:, enum:, range:, pattern:, length:, blank:, desc: description, example:, examples:)
       end
 
       private

data/lib/action_spec/schema/resolver.rb

@@ -15,7 +15,10 @@ module ActionSpec
       def resolve
         return resolve_missing unless present?
 
-        schema.cast(value, context:, coerce:, result:, path:)
+        return resolve_nil if value.nil?
+        return resolve_blank if blank_disallowed?
+
+        finalize(schema.cast(value, context:, coerce:, result:, path:))
       end
 
       private
@@ -36,15 +39,35 @@ module ActionSpec
 
         def resolve_missing
           if schema.default.respond_to?(:call)
-            return schema.cast(evaluate_default(schema.default), context:, coerce:, result:, path:)
+            return finalize(schema.cast(evaluate_default(schema.default), context:, coerce:, result:, path:))
           end
-          return schema.cast(schema.default, context:, coerce:, result:, path:) unless schema.default.nil?
-          return schema.materialize_missing(context:, coerce:, result:, path:) unless field.required?
+          return finalize(schema.cast(schema.default, context:, coerce:, result:, path:)) unless schema.default.nil?
+          return finalize(schema.materialize_missing(context:, coerce:, result:, path:)) unless field.required?
 
           result.add_error(path.join("."), :required)
           Schema::Missing
         end
 
+        def resolve_nil
+          result.add_error(path.join("."), field.required? ? :required : :blank)
+          Schema::Missing
+        end
+
+        def resolve_blank
+          result.add_error(path.join("."), :blank)
+          Schema::Missing
+        end
+
+        def blank_disallowed?
+          !schema.blank_allowed? && value.respond_to?(:blank?) && value.blank?
+        end
+
+        def finalize(resolved)
+          return resolved if resolved.equal?(Schema::Missing)
+
+          field.transform_value(resolved, context:)
+        end
+
         def evaluate_default(default_proc)
           return context.instance_exec(&default_proc) if context && default_proc.arity.zero?
           return default_proc.call(context) if context && default_proc.arity == 1

data/lib/action_spec/schema/scalar.rb

@@ -14,7 +14,7 @@ module ActionSpec
         candidate = TypeCaster.cast(type, value)
       rescue TypeCaster::CastError => error
         result.add_error(path.join("."), :invalid_type, expected: error.expected)
-        nil
+        Schema::Missing
       else
         return candidate if candidate.nil?
 
@@ -23,7 +23,7 @@ module ActionSpec
       end
 
       def copy
-        self.class.new(type, default:, enum:, range:, pattern:, length:, allow_nil:, allow_blank:, desc: description, example:, examples:)
+        self.class.new(type, default:, enum:, range:, pattern:, length:, blank:, desc: description, example:, examples:)
       end
     end
   end

data/lib/action_spec/schema/type_caster.rb

@@ -25,7 +25,7 @@ module ActionSpec
           return cast_decimal(value) if normalized == :decimal
 
           active_model_type_for(normalized).cast(value).tap do |casted|
-            raise CastError, normalized if casted.nil? && value.present?
+            raise CastError, normalized if casted.nil? && !value.nil?
           end
         end
 

data/lib/action_spec/schema.rb

@@ -12,7 +12,8 @@ require "action_spec/schema/type_caster"
 module ActionSpec
   module Schema
     Missing = Object.new.freeze
-    OPTION_KEYS = %i[default desc enum range pattern length allow_nil allow_blank example examples].freeze
+    OPTION_KEYS = %i[default desc enum range pattern length blank allow_blank example examples].freeze
+    FIELD_OPTION_KEYS = (OPTION_KEYS + %i[required transform px px_key]).freeze
 
     class << self
       def build(type = nil, **options)
@@ -21,6 +22,17 @@ module ActionSpec
         from_definition(definition)
       end
 
+      def build_field(name, definition = nil, required: false, scopes: [])
+        Field.new(
+          name: field_name(name),
+          required: required_key?(name) || required || explicit_required?(definition),
+          schema: build_field_schema(strip_field_options(definition)),
+          transform: explicit_transform(definition),
+          px_key: explicit_px_key(definition),
+          scopes:
+        )
+      end
+
       def from_definition(definition)
         return Scalar.new(String) if definition.blank?
         return ArrayOf.new(from_definition(type: definition.first)) if definition.is_a?(Array) && definition.one?
@@ -42,13 +54,8 @@ module ActionSpec
 
       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:,
-            scopes:
-          )
+          field = build_field(name, definition, scopes:)
+          fields[field.name] = field
         end
       end
 
@@ -64,11 +71,61 @@ module ActionSpec
         return from_definition(type: definition) unless definition.is_a?(Hash)
 
         definition = definition.symbolize_keys
-        return from_definition(definition) if definition.key?(:type)
-        return from_definition(definition) if (definition.keys - OPTION_KEYS).present?
+        return from_definition(definition.except(:required)) if definition.key?(:type)
+        return from_definition(definition.except(:required)) if (definition.keys - FIELD_OPTION_KEYS).present?
+
+        from_definition(definition.except(:required).merge(type: String))
+      end
+
+      def schema_definition?(definition)
+        case definition
+        when Array
+          definition.one? && schema_definition?(definition.first)
+        when Hash
+          definition = definition.with_indifferent_access
+          return true if definition.key?(:type)
+          return true if definition.keys.all? { |key| FIELD_OPTION_KEYS.include?(key.to_sym) }
 
-        from_definition(definition.merge(type: String))
+          definition.any? do |name, value|
+            required_key?(name) || schema_definition?(value)
+          end
+        when Class
+          true
+        when Symbol
+          definition == :boolean || definition == :file || definition == :object
+        else
+          false
+        end
       end
+
+      private
+
+        def explicit_required?(definition)
+          definition.is_a?(Hash) && definition.symbolize_keys[:required] == true
+        end
+
+        def explicit_transform(definition)
+          definition.is_a?(Hash) ? definition.symbolize_keys[:transform] : nil
+        end
+
+        def explicit_px_key(definition)
+          return unless definition.is_a?(Hash)
+
+          options = definition.symbolize_keys
+          normalize_px_key(options[:px_key] || options[:px])
+        end
+
+        def normalize_px_key(value)
+          return if value.nil? || value == true || value == false
+
+          value.is_a?(String) || value.is_a?(Symbol) ? value.to_sym : value
+        end
+
+        def strip_field_options(definition)
+          return definition unless definition.is_a?(Hash)
+
+          definition.symbolize_keys.except(:required, :transform, :px, :px_key)
+        end
     end
   end
 end

data/lib/action_spec/validator/runner.rb

@@ -13,7 +13,7 @@ module ActionSpec
         result = ValidationResult.new
         merge_group!(result, endpoint.request.path, source: path_source, location: :path)
         merge_group!(result, endpoint.request.query, source: params_source, location: :query)
-        merge_group!(result, endpoint.request.body, source: params_source, location: :body)
+        merge_body!(result)
         merge_group!(result, endpoint.request.header, source: header_source, location: :headers)
         merge_group!(result, endpoint.request.cookie, source: cookie_source, location: :cookies)
         result
@@ -23,6 +23,15 @@ module ActionSpec
 
         attr_reader :endpoint, :controller, :coerce
 
+        def merge_body!(result)
+          if endpoint.request.body_required? && body_source.blank?
+            result.add_error("body", :required)
+            return
+          end
+
+          merge_group!(result, endpoint.request.body, source: body_source, location: :body)
+        end
+
         def merge_group!(result, group, source:, location:)
           group.fields.each do |field|
             value = resolve_field(field, result:, source:, location:)
@@ -49,6 +58,12 @@ module ActionSpec
           controller.params.to_unsafe_h
         end
 
+        def body_source
+          return params_source unless controller.request.respond_to?(:request_parameters)
+
+          controller.request.request_parameters || {}
+        end
+
         def path_source
           controller.request.path_parameters.except(:controller, :action)
         end
@@ -70,6 +85,7 @@ module ActionSpec
         end
 
         def storage_key(field, location)
+          return field.output_name if field.px_key.present?
           return field.name.to_s.tr("_", "-").downcase if location == :headers
 
           field.name

data/lib/action_spec/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: action_spec
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - zhandao