action_spec 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a01ddc76d37b180c1564c96963ccce0bbe32cc9efd4c29deede6e1c3e7a8f7c7
-  data.tar.gz: a97df2927f2f5df0fce593b2ff55fa123d983ab6023690326bce9634ead51b31
+  metadata.gz: 02c55ca1816d1b61ad17a4a735c1704bb887cc4f67d842a7ed351641c47e93d8
+  data.tar.gz: a148b5f034a92b4f6648c3deb5e29aa997588e6162cd761e3586e9840d6b0fa2
 SHA512:
-  metadata.gz: e5ba8be1ae92c054686603867e11cda5b1af8482113ae2fcd4b36303e9631f1bdfd3c915b5e724a84dcd3c20c29f2a3f46bb92f74654716c3037625125d00820
-  data.tar.gz: 0d8327b6f04162da2ceedf697ac0a0e3dde789584870ebde8c2769ac43e6bb00836a81386b61d519b2472cd4acd8ffaf19472bbd0490c7911f9295c5216d4ed4
+  metadata.gz: 1eb2aa363f52d5800497364315168186b3fb04fc0fc1541ebe2075a73284585a5302b68f48183f5163451607f53bddc42474a988a6549dcb4daf7849bd2bf9aa
+  data.tar.gz: 985e5bd7551b4f6bd9919209137c90cae86a3a2720113dacb01e421849fca4e16a602550fb833a920d703f997c97a2b8b87c49ceda5ce4ecefa9bfea1a641988

data/README.md

@@ -14,6 +14,8 @@ Concise and Powerful API Documentation Solution for Rails.
 - [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)
@@ -28,6 +30,7 @@ Concise and Powerful API Documentation Solution for Rails.
 - [Configuration And I18n](#configuration-and-i18n)
   - [Configuration](#configuration)
   - [I18n](#i18n)
+- [AI Generation Style Guide](#ai-generation-style-guide)
 
 ## Example
 
@@ -163,6 +166,8 @@ 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
@@ -171,6 +176,20 @@ doc {
 }
 ```
 
+### `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
 
 #### Parameter
@@ -465,6 +484,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
 px[:id]
@@ -596,11 +616,23 @@ ActionSpec.configure { |config|
 }
 ```
 
+## AI Generation Style Guide
+
+When using AI tools to generate Rails controller code, and the change involves parameter validation, type coercion, default values, or similar parameter contracts, these conventions work well with ActionSpec:
+
+- use `doc { }` or `doc("Summary") { }`; do not add the action name, and do not leave a blank line between the `doc` block and the action method
+- use `{ }` blocks inside `doc` as well; prefer them over `do ... end`
+- 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
+- when request parameters match model declarations, prefer `.schemas` to keep `doc` concise
+
 ## What Is Not Implemented Yet
 
 - reusable `components` generation
 - `$ref` generation and deduplication
-- `description`, `operationId`, `tags`, `externalDocs`, `deprecated`, and `security` on operations
+- `description`, `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

data/lib/action_spec/doc.rb

@@ -8,6 +8,8 @@ module ActionSpec
     extend ActiveSupport::Concern
 
     class_methods do
+      DryEntry = Struct.new(:block, :options, keyword_init: true)
+
       def action_specs
         @action_specs ||= begin
           parent = superclass.respond_to?(:action_specs) ? superclass.action_specs : {}
@@ -18,20 +20,24 @@ module ActionSpec
       def dry_blocks
         @dry_blocks ||= begin
           parent = superclass.respond_to?(:dry_blocks) ? superclass.dry_blocks : {}
-          parent.transform_values { |blocks| blocks.map(&:dup) }
+          parent.transform_values do |entries|
+            entries.map { |entry| DryEntry.new(block: entry.block, options: entry.options.deep_dup) }
+          end
         end
       end
 
       def doc(action_or_summary = nil, summary = nil, **options, &block)
         action_name, endpoint_summary = normalize_doc_arguments(action_or_summary, summary)
         action_name ||= infer_action_name(caller_locations(1, 1).first)
-        endpoint = Endpoint.new(action_name, summary: endpoint_summary, options:)
-        action_specs[action_name.to_sym] = apply_dry_blocks(endpoint).apply(block || proc {})
+        endpoint = Endpoint.new(action_name, summary: endpoint_summary, options: {})
+        endpoint = apply_dry_blocks(endpoint)
+        endpoint.options.merge!(options)
+        action_specs[action_name.to_sym] = endpoint.apply(block || proc {})
       end
 
-      def doc_dry(actions = :all, &block)
+      def doc_dry(actions = :all, **options, &block)
         Array(actions).each do |action|
-          (dry_blocks[action.to_sym] ||= []) << block
+          (dry_blocks[action.to_sym] ||= []) << DryEntry.new(block:, options:)
         end
       end
       alias api_dry doc_dry
@@ -49,8 +55,9 @@ module ActionSpec
         end
 
         def apply_dry_blocks(endpoint)
-          [*dry_blocks[:all], *dry_blocks[endpoint.action]].compact.each do |dry_block|
-            endpoint.apply(dry_block)
+          [*dry_blocks[:all], *dry_blocks[endpoint.action]].compact.each do |entry|
+            endpoint.options.merge!(entry.options)
+            endpoint.apply(entry.block) if entry.block
           end
           endpoint
         end

data/lib/action_spec/open_api/generator.rb

@@ -8,8 +8,25 @@ module ActionSpec
           document = new(application:, routes:, title:, version:, server_url:).call
 
           FileUtils.mkdir_p(File.dirname(output))
-          File.write(output, YAML.dump(document))
+          File.write(output, pretty_yaml(plain_data(document)))
         end
+
+        private
+
+          def pretty_yaml(document)
+            YAML.dump(document).gsub(/^(\s*)"\/([^"]+)":$/, '\1/\2:')
+          end
+
+          def plain_data(value)
+            case value
+            when Array
+              value.map { |item| plain_data(item) }
+            when Hash
+              value.each_with_object({}) { |(key, item), hash| hash[key] = plain_data(item) }
+            else
+              value
+            end
+          end
       end
 
       def initialize(application: nil, routes: nil, title: nil, version: nil, server_url: nil)
@@ -55,7 +72,7 @@ module ActionSpec
 
             hash[path] ||= ActiveSupport::OrderedHash.new
             route_verbs(route).each do |verb|
-              hash[path][verb] = Operation.new(endpoint).build
+              hash[path][verb] = Operation.new(endpoint, controller_path: controller.controller_path).build
             end
           end
         end

data/lib/action_spec/open_api/operation.rb

@@ -3,14 +3,17 @@
 module ActionSpec
   module OpenApi
     class Operation
-      def initialize(endpoint)
+      def initialize(endpoint, controller_path:)
         @endpoint = endpoint
+        @controller_path = controller_path
         @schema = Schema.new
       end
 
       def build
         {
           "summary" => endpoint.summary.presence,
+          "operationId" => operation_id,
+          "tags" => tags,
           "parameters" => parameters.presence,
           "requestBody" => schema.request_body(endpoint.request),
           "responses" => responses
@@ -19,7 +22,23 @@ module ActionSpec
 
       private
 
-        attr_reader :endpoint, :schema
+        attr_reader :endpoint, :controller_path, :schema
+
+        def tags
+          [endpoint.options[:tag].presence || controller_path.presence].compact
+        end
+
+        def operation_id
+          [primary_tag, endpoint.action].compact.join("_")
+        end
+
+        def primary_tag
+          resolved_tag&.to_s&.tr("/", "_")
+        end
+
+        def resolved_tag
+          endpoint.options[:tag].presence || controller_path.presence
+        end
 
         def parameters
           %i[path query header cookie].flat_map do |location|

data/lib/action_spec/open_api/schema.rb

@@ -105,16 +105,23 @@ module ActionSpec
 
         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?
+          apply_literal_option(definition, "default", schema.default) unless schema.default.respond_to?(:call)
           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_literal_option(definition, "example", schema.example)
+          apply_literal_option(definition, "examples", schema.examples)
           apply_range(definition, schema.range)
           definition
         end
 
+        def apply_literal_option(definition, key, value)
+          normalized = openapi_literal(value)
+          return if normalized.nil? || normalized.equal?(invalid_openapi_literal)
+
+          definition[key] = normalized
+        end
+
         def apply_range(definition, range)
           return if range.blank?
 
@@ -166,6 +173,31 @@ module ActionSpec
         def regex_source(pattern)
           pattern.is_a?(Regexp) ? pattern.source : pattern.to_s
         end
+
+        def openapi_literal(value)
+          case value
+          when nil, String, Integer, Float, TrueClass, FalseClass
+            value
+          when Array
+            normalized = value.map { |item| openapi_literal(item) }
+            return invalid_openapi_literal if normalized.any? { |item| item.equal?(invalid_openapi_literal) }
+
+            normalized
+          when Hash
+            value.each_with_object(ActiveSupport::OrderedHash.new) do |(key, item), normalized|
+              item = openapi_literal(item)
+              return invalid_openapi_literal if item.equal?(invalid_openapi_literal)
+
+              normalized[key.to_s] = item
+            end
+          else
+            invalid_openapi_literal
+          end
+        end
+
+        def invalid_openapi_literal
+          @invalid_openapi_literal ||= Object.new.freeze
+        end
     end
   end
 end

data/lib/action_spec/railtie.rb

@@ -1,5 +1,9 @@
 module ActionSpec
   class Railtie < ::Rails::Railtie
+    rake_tasks do
+      load File.expand_path("../tasks/action_spec_tasks.rake", __dir__)
+    end
+
     initializer "action_spec.controller" do
       ActiveSupport.on_load(:action_controller_base) do
         include ActionSpec::Doc

data/lib/action_spec/version.rb

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

data/lib/tasks/action_spec_tasks.rake

@@ -2,13 +2,16 @@ namespace :action_spec do
   desc "Generate an OpenAPI 3.2 document from ActionSpec controller docs"
   task gen: :environment do
     config = ActionSpec.config
+    output = Rails.root.join(ENV.fetch("OUTPUT", config.open_api_output)).to_s
 
     ActionSpec::OpenApi::Generator.generate!(
       application: Rails.application,
-      output: Rails.root.join(ENV.fetch("OUTPUT", config.open_api_output)).to_s,
+      output:,
       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
     )
+
+    puts "Generated OpenAPI document: #{output}"
   end
 end

metadata

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