action_spec 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 888d8ca36314d55e09ba317663b9fdee4e09895480d0c936658ba844268783ef
-  data.tar.gz: 4e36cb8eea3d23a338e558784ec8c72bb4bdfecc8c981d094c72784b0f88181e
+  metadata.gz: 6fccbffa8f14fb73bec7eade75add8f70d0371741999475ef292ed980d985ddc
+  data.tar.gz: 20f1b1d3b86826b1cb9d2ed3d72f0259ccd28c397790bbf8bc8fb8766cab0329
 SHA512:
-  metadata.gz: 8fb29df856db1970afb0b1b24c11316501f5edf6e9962f244d31af0dd13d150eaf02c1082e84c931d2ac77798dc2239b063092b4cda0dbbdc6d6fd28d3240df4
-  data.tar.gz: 2f0cc430e55895e929ca985723c0f8aa7b1be6549af05184f71f171b122afeda65ec47529c249aea93f7acf0d3ccede50405bcbc841af05ad00c62155a39d093
+  metadata.gz: 552c83ccebe73754cb2b6e160cbfb8774ea818e22e665a1ba6df322c5051e5ff7902b533d82c2c2a93f94fd0f631264e2e344521b67a3582576a27b5f4ce2144
+  data.tar.gz: 9585aa85edeb6654d00e06b7a0e2478aed741675d3d90e0b60c46ac99d267e68d13bbe30060f6b163b1869ac508b92c4509b8b0b0f69f3ae7d0c386da875afce

data/README.md

@@ -6,21 +6,31 @@ 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.
-
-## 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
+- 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
+
+- [OpenAPI Generation](#openapi-generation)
+- [Doc DSL](#doc-dsl)
+  - [`doc`](#doc)
+  - [`doc_dry`](#doc_dry)
+  - [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 Validated Values With `px`](#reading-validated-values-with-px)
+  - [Errors](#errors)
+  - [Default Rescue Behavior](#default-rescue-behavior)
+- [Configuration And I18n](#configuration-and-i18n)
+  - [Configuration](#configuration)
+  - [I18n](#i18n)
+
+## Example
 
 ```ruby
 class UsersController < ApplicationController
@@ -32,7 +42,7 @@ class UsersController < ApplicationController
     query :locale, String, default: "zh-CN"
     query :page, Integer, default: -> { 1 }
 
-    json data: {
+    form data: {
       name!: String,
       age: Integer,
       birthday: Date,
@@ -69,25 +79,58 @@ Then run:
 $ bundle
 ```
 
-## Usage
+## OpenAPI Generation
+
+Generate an OpenAPI document from the current Rails routes and ActionSpec controller docs:
+
+```bash
+bin/rails action_spec:gen
+```
+
+By default, this writes to:
+
+```text
+docs/openapi.yml
+```
+
+For one-off runs, environment variables can override the default output path and document metadata:
+
+```bash
+bin/rails action_spec:gen \
+  OUTPUT=docs/openapi.yml \
+  TITLE="My API" \
+  VERSION="2026.03" \
+  SERVER_URL="https://api.example.com"
+```
+
+Notes:
+
+- only routed controller actions with a matching `doc` declaration are included
+- Rails paths such as `/users/:id(.:format)` are rendered as `/users/{id}`
+- parameters, request bodies, and response descriptions are generated from the current DSL support
+- if config and environment variables do not provide `TITLE` or `VERSION`, ActionSpec falls back to application-derived defaults
+
+## Doc DSL
 
-### How To Bind `doc`
+### `doc`
 
-Default form, with action inferred from the next instance method:
+With action inferred from the next instance method:
 
 ```ruby
 doc {
-  json data: { name!: String }
+  form data: {    # <= request body DSL
+    name!: String # <= schema DSL
+  }
 }
 def create
 end
 ```
 
-You can still provide a summary in the default form:
+Provide a summary:
 
 ```ruby
 doc("Create user") {
-  json data: { name!: String }
+  form data: { name!: String }
 }
 def create
 end
@@ -97,13 +140,13 @@ You can also bind it explicitly when you want the action name declared in place:
 
 ```ruby
 doc(:create, "Create user") {
-  json data: { name!: String }
+  form data: { name!: String }
 }
 def create
 end
 ```
 
-### Shared Declarations With `doc_dry`
+### `doc_dry`
 
 ```ruby
 class ApplicationController < ActionController::API
@@ -122,11 +165,7 @@ 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:
+#### Parameter
 
 ```ruby
 header  :Authorization, String
@@ -171,7 +210,7 @@ in_query!(
 )
 ```
 
-#### Request Bodies
+#### request body 
 
 General form:
 
@@ -199,7 +238,7 @@ 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
+#### Response 
 
 ```ruby
 response 200, desc: "success"
@@ -210,9 +249,9 @@ error 401, "unauthorized"
 
 Response declarations are stored as metadata now. They are not yet used to render responses automatically.
 
-### Schema Writing
+## Schemas
 
-#### Required Fields
+#### Declare A Required Field
 
 Use `!` in either place:
 
@@ -233,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:
 
@@ -241,8 +280,7 @@ Scalar types currently supported by validation/coercion:
 - `Integer`
 - `Float`
 - `BigDecimal`
-- `:boolean`
-- host-defined `Boolean` constant, if the host app already defines one
+- `:boolean` / `Boolean`
 - `Date`
 - `DateTime`
 - `Time`
@@ -257,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:
 
@@ -290,14 +312,87 @@ 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
 
 #### `validate_params!`
@@ -396,12 +491,18 @@ The default JSON response is:
 }
 ```
 
+## Configuration And I18n
+
 ### Configuration
 
 ```ruby
 ActionSpec.configure do |config|
   config.rescue_invalid_parameters = true
   config.invalid_parameters_status = :bad_request
+  config.open_api_output = "docs/openapi.yml"
+  config.open_api_title = "My API"
+  config.open_api_version = "2026.03"
+  config.open_api_server_url = "https://api.example.com"
 
   config.error_messages[:invalid_type] = ->(_attribute, options) do
     "should be coercible to #{options.fetch(:expected)}"
@@ -438,6 +539,22 @@ Available config keys:
   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.
+
 ### I18n
 
 ActionSpec loads its own locale files and uses `ActiveModel::Errors`, so you can override both messages and attribute names:
@@ -466,12 +583,26 @@ ActionSpec.configure do |config|
 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`
+## What Is Not Implemented Yet
+
+- 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/configuration.rb

@@ -3,7 +3,8 @@
 module ActionSpec
   class Configuration
     attr_accessor :invalid_parameters_exception_class, :invalid_parameters_status, :rescue_invalid_parameters,
-                  :invalid_parameters_renderer
+                  :invalid_parameters_renderer, :open_api_output, :open_api_title, :open_api_version,
+                  :open_api_server_url
     attr_reader :error_messages
 
     def initialize
@@ -11,6 +12,10 @@ module ActionSpec
       @invalid_parameters_status = :bad_request
       @rescue_invalid_parameters = true
       @invalid_parameters_renderer = nil
+      @open_api_output = "docs/openapi.yml"
+      @open_api_title = nil
+      @open_api_version = nil
+      @open_api_server_url = nil
       @error_messages = ActiveSupport::HashWithIndifferentAccess.new
     end
 
@@ -31,6 +36,10 @@ module ActionSpec
         copy.invalid_parameters_status = invalid_parameters_status
         copy.rescue_invalid_parameters = rescue_invalid_parameters
         copy.invalid_parameters_renderer = invalid_parameters_renderer
+        copy.open_api_output = open_api_output
+        copy.open_api_title = open_api_title
+        copy.open_api_version = open_api_version
+        copy.open_api_server_url = open_api_server_url
         copy.error_messages = error_messages.deep_dup
       end
     end

data/lib/action_spec/open_api/document.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module ActionSpec
+  module OpenApi
+    class Document
+      OPENAPI_VERSION = "3.2.0"
+
+      def initialize(title:, version:, server_url: nil)
+        @title = title
+        @version = version
+        @server_url = server_url
+      end
+
+      def build(paths:)
+        {
+          "openapi" => OPENAPI_VERSION,
+          "info" => {
+            "title" => title,
+            "version" => version
+          },
+          "paths" => paths
+        }.tap do |document|
+          document["servers"] = [{ "url" => server_url }] if server_url.present?
+        end
+      end
+
+      private
+
+        attr_reader :title, :version, :server_url
+    end
+  end
+end

data/lib/action_spec/open_api/generator.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module ActionSpec
+  module OpenApi
+    class Generator
+      class << self
+        def generate!(application: nil, routes: nil, output:, title: nil, version: nil, server_url: nil)
+          document = new(application:, routes:, title:, version:, server_url:).call
+
+          FileUtils.mkdir_p(File.dirname(output))
+          File.write(output, YAML.dump(document))
+        end
+      end
+
+      def initialize(application: nil, routes: nil, title: nil, version: nil, server_url: nil)
+        @application = application
+        @routes = routes
+        @title = title
+        @version = version
+        @server_url = server_url
+      end
+
+      def call
+        Document.new(
+          title: resolved_title,
+          version: resolved_version,
+          server_url:
+        ).build(paths:)
+      end
+
+      private
+
+        attr_reader :application, :routes, :title, :version, :server_url
+
+        def resolved_title
+          return title if title.present?
+
+          application_name = application&.class&.name.to_s.sub(/::Application\z/, "").sub(/Application\z/, "")
+          application_name.demodulize.titleize.presence || "API"
+        end
+
+        def resolved_version
+          version.presence || "1.0.0"
+        end
+
+        def paths
+          route_definitions.each_with_object(ActiveSupport::OrderedHash.new) do |route, hash|
+            next unless (controller = controller_for(route))
+            next unless controller.respond_to?(:action_spec_for)
+            next unless (endpoint = controller.action_spec_for(route_action(route)))
+
+            path = normalized_path(route)
+            next if path.blank?
+
+            hash[path] ||= ActiveSupport::OrderedHash.new
+            route_verbs(route).each do |verb|
+              hash[path][verb] = Operation.new(endpoint).build
+            end
+          end
+        end
+
+        def route_definitions
+          return routes if routes
+
+          application.routes.routes
+        end
+
+        def controller_for(route)
+          controller_name = route_defaults(route)[:controller].presence
+          return unless controller_name
+
+          "#{controller_name.camelize}Controller".safe_constantize
+        end
+
+        def route_action(route)
+          route_defaults(route).fetch(:action).to_sym
+        end
+
+        def route_defaults(route)
+          defaults =
+            if route.respond_to?(:defaults)
+              route.defaults
+            elsif route.respond_to?(:requirements)
+              route.requirements
+            else
+              route[:defaults]
+            end
+
+          defaults.to_h.symbolize_keys
+        end
+
+        def route_verbs(route)
+          raw_verb =
+            if route.respond_to?(:verb) && route.verb.respond_to?(:source)
+              route.verb.source
+            elsif route.respond_to?(:verb)
+              route.verb.to_s
+            else
+              route[:verb].to_s
+            end
+
+          raw_verb.gsub(/[$^]/, "").split("|").filter_map { |verb| verb.presence&.downcase }
+        end
+
+        def normalized_path(route)
+          raw_path =
+            if route.respond_to?(:path) && route.path.respond_to?(:spec)
+              route.path.spec.to_s
+            elsif route.respond_to?(:path)
+              route.path.to_s
+            else
+              route[:path].to_s
+            end
+
+          raw_path
+            .sub(/\(\.:format\)\z/, "")
+            .gsub(/:(\w+)/, '{\1}')
+        end
+    end
+  end
+end

data/lib/action_spec/open_api/operation.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module ActionSpec
+  module OpenApi
+    class Operation
+      def initialize(endpoint)
+        @endpoint = endpoint
+        @schema = Schema.new
+      end
+
+      def build
+        {
+          "summary" => endpoint.summary.presence,
+          "parameters" => parameters.presence,
+          "requestBody" => schema.request_body(endpoint.request),
+          "responses" => responses
+        }.compact
+      end
+
+      private
+
+        attr_reader :endpoint, :schema
+
+        def parameters
+          %i[path query header cookie].flat_map do |location|
+            endpoint.request.public_send(location).fields.map do |field|
+              schema.parameter(field, location:)
+            end
+          end
+        end
+
+        def responses
+          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" }
+          end
+        end
+    end
+  end
+end

data/lib/action_spec/open_api/schema.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module ActionSpec
+  module OpenApi
+    class Schema
+      LOCATION_MAP = {
+        header: "header",
+        path: "path",
+        query: "query",
+        cookie: "cookie"
+      }.freeze
+
+      MEDIA_TYPE_MAP = {
+        json: "application/json",
+        form: "multipart/form-data"
+      }.freeze
+
+      def parameter(field, location:)
+        {
+          "name" => parameter_name(field, location),
+          "in" => LOCATION_MAP.fetch(location),
+          "required" => location == :path ? true : field.required?,
+          "schema" => schema_for(field.schema)
+        }.tap do |parameter|
+          if (description = field.schema.description).present?
+            parameter["description"] = description
+          end
+        end
+      end
+
+      def request_body(request)
+        content = request.body_media_types.each_with_object(ActiveSupport::OrderedHash.new) do |(media_type, fields), hash|
+          hash[MEDIA_TYPE_MAP.fetch(media_type, media_type.to_s)] = {
+            "schema" => object_schema(fields.fields)
+          }
+        end
+        return if content.empty?
+
+        { "content" => content }
+      end
+
+      def schema_for(schema)
+        case schema
+        when ActionSpec::Schema::Scalar then scalar_schema(schema)
+        when ActionSpec::Schema::ObjectOf then object_schema(schema.fields.values, schema:)
+        when ActionSpec::Schema::ArrayOf then array_schema(schema)
+        else { "type" => "string" }
+        end
+      end
+
+      private
+
+        def parameter_name(field, location)
+          return field.name.to_s if location != :header
+
+          field.name.to_s.split("_").map(&:capitalize).join("-")
+        end
+
+        def scalar_schema(schema)
+          type = scalar_type(schema.type)
+          definition =
+            case type
+            when "string"
+              { "type" => "string" }
+            when "integer"
+              { "type" => "integer" }
+            when "number"
+              { "type" => "number", "format" => number_format(schema.type) }.compact
+            when "boolean"
+              { "type" => "boolean" }
+            when "file"
+              { "type" => "string", "format" => "binary" }
+            when "object"
+              { "type" => "object" }
+            else
+              { "type" => "string" }
+            end
+
+          definition["format"] = string_format(schema.type) if string_format(schema.type)
+          apply_common_options(definition, schema)
+        end
+
+        def object_schema(fields, schema: nil)
+          definition = {
+            "type" => "object",
+            "properties" => fields.each_with_object(ActiveSupport::OrderedHash.new) do |field, properties|
+              properties[field.name.to_s] = schema_for(field.schema)
+            end
+          }
+
+          required = fields.select(&:required?).map { |field| field.name.to_s }
+          definition["required"] = required if required.any?
+
+          schema ? apply_common_options(definition, schema) : definition
+        end
+
+        def array_schema(schema)
+          definition = {
+            "type" => "array",
+            "items" => schema_for(schema.item)
+          }
+
+          apply_common_options(definition, schema)
+        end
+
+        def apply_common_options(definition, schema)
+          definition["description"] = schema.description if schema.description.present?
+          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)
+          definition
+        end
+
+        def apply_range(definition, range)
+          return if range.blank?
+
+          rules = range.symbolize_keys
+          definition["minimum"] = rules[:ge] if rules.key?(:ge)
+          definition["exclusiveMinimum"] = rules[:gt] if rules.key?(:gt)
+          definition["maximum"] = rules[:le] if rules.key?(:le)
+          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"
+          when :integer then "integer"
+          when :float, :decimal then "number"
+          when :boolean then "boolean"
+          when :date, :datetime, :time then "string"
+          when :file then "file"
+          when :object then "object"
+          else "string"
+          end
+        end
+
+        def string_format(type)
+          case ActionSpec::Schema::TypeCaster.normalize(type)
+          when :date then "date"
+          when :datetime then "date-time"
+          when :time then "time"
+          end
+        end
+
+        def number_format(type)
+          case ActionSpec::Schema::TypeCaster.normalize(type)
+          when :float then "float"
+          when :decimal then "double"
+          end
+        end
+
+        def regex_source(pattern)
+          pattern.is_a?(Regexp) ? pattern.source : pattern.to_s
+        end
+    end
+  end
+end

data/lib/action_spec/open_api.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "fileutils"
+require "action_spec/open_api/document"
+require "action_spec/open_api/operation"
+require "action_spec/open_api/schema"
+require "action_spec/open_api/generator"

data/lib/action_spec/railtie.rb

@@ -10,5 +10,11 @@ module ActionSpec
         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:)
+        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
+      attr_reader :default, :enum, :range, :pattern, :length, :allow_nil, :allow_blank, :description, :example, :examples
 
       def initialize(options = {})
         options = options.symbolize_keys
@@ -11,8 +11,12 @@ 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]
+        @example = options[:example]
+        @examples = options[:examples]
       end
 
       def materialize_missing(_context:, _coerce:, _result:, _path:)

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:)
+        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:)
+        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.1.0"
+  VERSION = "1.0.0"
 end

data/lib/action_spec.rb

@@ -8,6 +8,7 @@ require "action_spec/validation_result"
 require "action_spec/invalid_parameters"
 require "action_spec/doc"
 require "action_spec/schema"
+require "action_spec/open_api"
 require "action_spec/validator"
 require "action_spec/railtie"
 

data/lib/tasks/action_spec_tasks.rake

@@ -1,4 +1,14 @@
-# desc "Explaining what the task does"
-# task :action_spec do
-#   # Task goes here
-# end
+namespace :action_spec do
+  desc "Generate an OpenAPI 3.2 document from ActionSpec controller docs"
+  task gen: :environment do
+    config = ActionSpec.config
+
+    ActionSpec::OpenApi::Generator.generate!(
+      application: Rails.application,
+      output: Rails.root.join(ENV.fetch("OUTPUT", config.open_api_output)).to_s,
+      title: ENV["TITLE"].presence || config.open_api_title,
+      version: ENV["VERSION"].presence || config.open_api_version,
+      server_url: ENV["SERVER_URL"].presence || config.open_api_server_url
+    )
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: action_spec
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - zhandao
@@ -62,8 +62,14 @@ files:
 - lib/action_spec/doc/endpoint.rb
 - lib/action_spec/header_hash.rb
 - lib/action_spec/invalid_parameters.rb
+- lib/action_spec/open_api.rb
+- lib/action_spec/open_api/document.rb
+- lib/action_spec/open_api/generator.rb
+- lib/action_spec/open_api/operation.rb
+- 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