action_spec 1.3.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 02c55ca1816d1b61ad17a4a735c1704bb887cc4f67d842a7ed351641c47e93d8
-  data.tar.gz: a148b5f034a92b4f6648c3deb5e29aa997588e6162cd761e3586e9840d6b0fa2
+  metadata.gz: 9218555ca7d33709a7a5b22528f6900358e36247c123e521f2342d7a36ac02b5
+  data.tar.gz: e771af58669e707ccbcc922b6d9afa726a2b25817ab4836e01ce1154bd22344b
 SHA512:
-  metadata.gz: 1eb2aa363f52d5800497364315168186b3fb04fc0fc1541ebe2075a73284585a5302b68f48183f5163451607f53bddc42474a988a6549dcb4daf7849bd2bf9aa
-  data.tar.gz: 985e5bd7551b4f6bd9919209137c90cae86a3a2720113dacb01e421849fca4e16a602550fb833a920d703f997c97a2b8b87c49ceda5ce4ecefa9bfea1a641988
+  metadata.gz: 7d03ee8f19de7c1c874302344eadf224f9aa3fba2dab228f2f4b44448a2865ba53dd97385587b6b9691308e4a987048b1eab6e5f55a1b03ef93424a643857a0c
+  data.tar.gz: 357fe37dc9a591740079c76dd3e4238a9485cb0d1e57ab020bed09bf737d1937ef22b777f8b062f78473fe497965c2df754ee3858a97f77bdd59674002cdda69

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,31 @@ 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. [`px` is Whitelist Extraction](#px-is-whitelist-extraction)
+   4. [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
 
@@ -41,28 +45,27 @@ class UsersController < ApplicationController
   doc {
     header :Authorization, String
     path :account_id, Integer
-    query :locale, String, default: "zh-CN"
-    query :page, Integer, default: -> { 1 }
+    query :locale, String, default: "zh-CN", transform: -> { it.downcase }
+    query :key_number, Integer, default: -> { it + 1 }, px: :key
 
     form data: {
-      name!: String,
-      age: Integer,
+      name!: { type: String, transform: :strip },
       birthday: Date,
       admin: { type: :boolean, default: false },
-      tags: [String],
-      profile: {
-        nickname!: String
-      }
+      tags: [{ id: Integer, content!: { type: String, blank: false } }],
+      profile: { nickname!: String }
     }
 
-    response 200, desc: "success"
+    response 200, "success", :json, data: { code: Integer, result: [Hash] }
+    errors 400, "client errors", {
+      invalid_params: { code: 1234, message: "parameters are invalid" },
+      missing_params: { code: 1235, message: "parameters are missing" }
+    }
   }
   def create
-    User.create!(
-      account_id: px[:account_id],
-      name: px[:name],
-      birthday: px[:birthday],
-      admin: px[:admin]
+    User.find(px[:account_id]).update!(
+      key: px[:key], name: px[:name],
+      **px.slice(:birthday, :admin, :profile)
     )
   end
 end
@@ -95,7 +98,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 +152,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 +181,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 +199,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:
 
@@ -237,7 +237,7 @@ in_query!(
 )
 ```
 
-#### request body 
+#### Request body
 
 General form:
 
@@ -249,11 +249,9 @@ Convenience helpers:
 
 ```ruby
 json data: { name!: String }
-
 json! data: { name!: String }
 
 form data: { file!: File, position: String }
-
 form! data: { file!: File }
 ```
 
@@ -263,16 +261,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:
 
-#### OpenAPI
+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`
+
+`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 +288,7 @@ doc {
     query :user_id, Integer
     form data: { name: String }
   }
+  form data: { not_in_scope: String }
 }
 ```
 
@@ -292,16 +298,53 @@ Then read it from `px.scope`:
 px.scope[:user] # => { user_id: 1, name: "Tom" }
 ```
 
-#### Response 
+You can also trim custom scope buckets with `compact:` or `compact_blank:`:
+
+```ruby
+doc {
+  scope(:search, compact: true) {
+    query :page, Integer, transform: -> { nil }, px: :page_number
+    query :keyword, String
+  }
+
+  scope(:filters, compact_blank: true) {
+    query :q, String, transform: :strip
+    query :nickname, String, transform: -> { "" }
+  }
+}
+
+px.scope[:search]  # => { keyword: "rails" }
+px.scope[:filters] # => { q: "ruby" }
+```
+
+These options only apply to the custom `px.scope[:name]` bucket defined by that `scope`, and use shallow hash compaction.
+
+#### Response
 
 ```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 +367,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
 
@@ -339,24 +386,38 @@ Scalar types currently supported by validation/coercion:
 - `DateTime`
 - `Time`
 - `File`
-- `Object`
+- `Object` / `Hash`
 
-Nested forms:
+```ruby
+query :page, Integer
+form data: { file: File }
+```
+
+Object and Nested Object forms:
 
 ```ruby
 json data: {
-  tags: [String],
-  profile: {
-    nickname!: String
-  },
-  settings: { type: Object },
-  users: [{ id: Integer }]
+  settings: Object,
+  # == settings: { type: Object }
+  # == settings: { type: Hash }
+  # == settings: { type: { } }
+
+  profile: { nickname!: String },
+  tags: [],
+  # == tags: { type: [] }
+  foo: [{ id: Integer }],
+
+  users: {
+    type: { name!: String },
+    default: { name: "Tom" },
+    transform: -> { { name: it[:name].downcase } }
+  }
 }
 ```
 
-#### Field Options
+When you write `xx: { type: ... }`, the type of `xx` comes from `type`. In other words, `type` is a reserved schema keyword here, not a normal nested field name.
 
-These options are currently used by the validator:
+#### Field Options
 
 ```ruby
 query :page, Integer, default: 1
@@ -364,18 +425,48 @@ 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
+query :end_at, Integer, validate: -> { it >= px[:start_at] }
 ```
 
-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`
+- `validate` accepts a `Proc` and runs **after all parameters have been resolved, coerced, transformed, and written into `px`**
+- `validate` runs in the current controller context, so it can read `px` and call methods such as `current_user`
+- when `validate` returns `false` or `nil`, the field adds an `invalid` error
+
+About nested object fields
+
+Inner field options run first, and the outer object field runs last.  
+In other words, nested `transform` / `px` first participate in building the object, and after the whole object has been built, the outer field receives that final object and continues processing it.  
+Only after the whole object tree has finished resolving, coercing, and transforming does ActionSpec enter the post-`validate` phase: inner field `validate` callbacks run first, and outer object field `validate` callbacks run afterwards.
+
+```ruby
+json data: {
+  user: {
+    type: {
+      name: { type: String, transform: :strip, px: :nickname }
+    },
+    transform: -> { { name: it[:nickname].downcase } }
+  }
+}
+
+px[:user] # => { "name" => "tom" }
+```
 
-- `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
 
@@ -405,10 +496,16 @@ You can also limit the exported fields:
 User.schemas(only: %i[name phone role])
 ```
 
+`bang:` defaults to `true`, so required fields are emitted as bang keys such as `"name!"`. If you prefer plain keys, you can pass `bang: false`, and required fields will be emitted as `required: true` instead:
+
+```ruby
+User.schemas(bang: false)
+```
+
 ActionSpec extracts schema-relevant information from ActiveRecord / ActiveModel when available, including:
 
 - field type
-- requiredness, rendered as bang keys such as `"name!"`
+- requiredness, rendered either as bang keys such as `"name!"` or as `required: true` when `bang: false`
 - enum values from `enum`
 - `default`
 - `desc` from column comments
@@ -425,6 +522,13 @@ User.schemas
 #   "phone!" => { type: String, length: { maximum: 13 }, pattern: /\A1\d{10}\z/ },
 #   "role" => { type: String, enum: %w[admin member visitor] }
 # }
+
+User.schemas(bang: false)
+# {
+#   "name" => { type: String, required: true, desc: "user name", length: { maximum: 20 } },
+#   "phone" => { type: String, required: true, length: { maximum: 13 }, pattern: /\A1\d{10}\z/ },
+#   "role" => { type: String, enum: %w[admin member visitor] }
+# }
 ```
 
 #### Type And Boundary Matrix
@@ -484,6 +588,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
@@ -502,12 +607,13 @@ px.scope[:query]
 px.scope[:body]
 px.scope[:headers]
 px.scope[:cookies]
+px.scope[:the_scope_you_defined]
 ```
 
 Notes:
 
 - 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]`
+- `px` itself is an `ActiveSupport::HashWithIndifferentAccess`, and nested object values such as `px[:profile]` are also returned as indifferent hashes
 - 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:
 
@@ -519,6 +625,28 @@ px.scope[:headers]["HTTP_AUTHORIZATION"]
 
 - original `params` are not mutated
 
+### `px` is Whitelist Extraction
+
+```ruby
+json data: {
+  profile: {
+    nickname: String
+  }
+}
+
+# request params
+{
+  profile: {
+    nickname: "Neo",
+    role: "admin"
+  }
+}
+
+px[:profile] # => { "nickname" => "Neo" }
+```
+
+Undeclared fields are filtered out, including extra keys inside nested objects.
+
 ### Errors
 
 Validation errors are stored in `ActiveModel::Errors`.
@@ -555,6 +683,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 +693,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 +738,8 @@ 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 `!` but not `required: true`
+- 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 +750,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 +760,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