action_spec 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 888d8ca36314d55e09ba317663b9fdee4e09895480d0c936658ba844268783ef
-  data.tar.gz: 4e36cb8eea3d23a338e558784ec8c72bb4bdfecc8c981d094c72784b0f88181e
+  metadata.gz: bf40844c78d8e8281f129c65e12bf07d9fc8ebabc18bd47c717d779cbc90fa99
+  data.tar.gz: 1552ea6a7da3f13b02febfd4eea39b05b437db5efaa93bb99320662b9f96e98c
 SHA512:
-  metadata.gz: 8fb29df856db1970afb0b1b24c11316501f5edf6e9962f244d31af0dd13d150eaf02c1082e84c931d2ac77798dc2239b063092b4cda0dbbdc6d6fd28d3240df4
-  data.tar.gz: 2f0cc430e55895e929ca985723c0f8aa7b1be6549af05184f71f171b122afeda65ec47529c249aea93f7acf0d3ccede50405bcbc841af05ad00c62155a39d093
+  metadata.gz: 02e508bf9545f6848c351d96e7b95d4b7f22219322d365bba632f793722899922ee9ef347c147d4c98987cc9bf9b1ef18f70436ba105a7e695d0bb96f92acb47
+  data.tar.gz: cb9023dc36b73d1c155854200d726eb3fe3cb1dea03734da8fde6f64cf93cf58a2376eba90e77ccaff66c29ecbda220c6376037608a5d9fb2c0be702192c51f4

data/README.md

@@ -8,19 +8,28 @@ Concise and Powerful API Documentation Solution for Rails.
 - 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
+## Table Of Contents
+
+- [OpenAPI Generation](#openapi-generation)
+- [Doc DSL](#doc-dsl)
+  - [`doc`](#doc)
+  - [`doc_dry`](#doc_dry)
+  - [DSL Reference](#dsl-reference)
+- [Schemas](#schemas)
+  - [Required Fields](#required-fields)
+  - [Supported Runtime Types](#supported-runtime-types)
+  - [Type And Boundary Matrix](#type-and-boundary-matrix)
+  - [Supported Runtime Options](#supported-runtime-options)
+- [Parameter Validation And Type Coercion](#parameter-validation-and-type-coercion)
+  - [Validation Flow](#validation-flow)
+  - [Reading Validated Values With `px`](#reading-validated-values-with-px)
+  - [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 +41,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 +78,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 +139,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 +164,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 +209,7 @@ in_query!(
 )
 ```
 
-#### Request Bodies
+#### request body 
 
 General form:
 
@@ -199,7 +237,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,7 +248,7 @@ error 401, "unauthorized"
 
 Response declarations are stored as metadata now. They are not yet used to render responses automatically.
 
-### Schema Writing
+## Schemas
 
 #### Required Fields
 
@@ -241,8 +279,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`
@@ -298,6 +335,8 @@ These options are currently accepted as metadata, mainly for future OpenAPI work
 - `allow_nil`
 - `allow_blank`
 
+## Parameter Validation And Type Coercion
+
 ### Validation Flow
 
 #### `validate_params!`
@@ -396,12 +435,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 +483,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,7 +527,7 @@ ActionSpec.configure do |config|
 end
 ```
 
-### What Is Not Implemented Yet
+## What Is Not Implemented Yet
 
 - OpenAPI document generation
 - automatic response rendering from `response`

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,119 @@
+# 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
+            hash[path][route_verb(route)] = Operation.new(endpoint).build
+          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_verb(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("|").find(&:present?).to_s.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,160 @@
+# 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?
+          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 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/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:, 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, :allow_nil, :allow_blank, :description, :example, :examples
 
       def initialize(options = {})
         options = options.symbolize_keys
@@ -13,6 +13,9 @@ module ActionSpec
         @pattern = options[:pattern]
         @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:, 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:, allow_nil:, allow_blank:, desc: description, example:, examples:)
       end
     end
   end

data/lib/action_spec/version.rb

@@ -1,3 +1,3 @@
 module ActionSpec
-  VERSION = "0.1.0"
+  VERSION = "0.2.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: 0.2.0
 platform: ruby
 authors:
 - zhandao
@@ -62,6 +62,11 @@ 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/array_of.rb