dry_validation_openapi 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 29d8e1b449631809fa220bb41125221b44443097ae83533a7b71c97cc88d6e7e
+  data.tar.gz: d070b609ff5ae658efe41c6ede707c4520473195819dd52b918b6e39779a5297
+SHA512:
+  metadata.gz: a58f1f2e0ad933889dbd367d23a148ba9dc1ed537e9d999ba6cfeccefc01b9e59e28b66d6c7f85b7392bd4357f8d07382785e712afda8267bfc1c7b7a539f776
+  data.tar.gz: 2fcb73cc379258c609bec33e59133cf398161930677ec1b46da2626188288acf4d9b748c5d295cf221c464b7d0ef59d89d2e2d46ee06431c0c96f35cc320e71d

data/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-12-11
+
+### Added
+- Initial release
+- Support for required and optional fields
+- Support for basic types: string, integer, float, decimal, boolean
+- Type format specifications (int32, double, float, date, date-time)
+- Support for array types with item schemas
+- Support for nested objects/hashes with properties
+- Support for arrays of objects with nested schemas
+- Support for multiple nested objects at the same level
+- Support for both `.value()` and `.filled()` predicates
+- `Convertable` module for easy integration with dry-validation contracts
+- Static parsing using Ruby's built-in Ripper parser
+- Zero runtime dependencies (besides Ruby standard library)
+
+### Features
+- `extend DryValidationOpenapi::Convertable` to add `.open_api_schema` method to contracts
+- Automatic parent tracking for nested schemas
+- OpenAPI 3.0 compatible schema generation
+- Works with rswag and other OpenAPI tools

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 [Your Name]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,245 @@
+# DryValidationOpenapi
+
+Automatically generate OpenAPI 3.0 schemas from [dry-validation](https://dry-rb.org/gems/dry-validation/) contracts for use with [rswag](https://github.com/rswag/rswag) and other OpenAPI tools.
+
+Instead of manually writing OpenAPI schemas for your API documentation, this gem extracts type information directly from your dry-validation contract definitions using static parsing.
+
+## Features
+
+- 🎯 **Zero runtime overhead** - Uses static parsing, no contract instantiation needed
+- 🔄 **Automatic conversion** - Converts dry-validation types to OpenAPI types with formats
+- 🪆 **Nested schemas** - Handles nested objects and arrays of objects
+- 📝 **Simple API** - Just `extend` your contract and call `.open_api_schema`
+- ✅ **Type formats** - Includes OpenAPI format specifications (int32, double, date-time, etc.)
+
+## Supported Features
+
+### ✅ Currently Supported
+
+- [x] Required and optional fields
+- [x] Basic types: string, integer, float, decimal, boolean
+- [x] Type formats: int32, double, float, date, date-time
+- [x] Array types with item schemas
+- [x] Nested objects/hashes with properties
+- [x] Arrays of objects with nested schemas
+- [x] Multiple nested objects at the same level
+- [x] `.value()` and `.filled()` predicates
+
+### 📋 Not Yet Implemented
+
+- [ ] Custom type formats (email, uuid, etc.)
+- [ ] Descriptions and examples
+- [ ] Min/max constraints
+- [ ] Enums
+- [ ] Custom rules/validations
+- [ ] Pattern validations
+- [ ] Maybe/nil handling
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'dry_validation_openapi'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install dry_validation_openapi
+```
+
+## Usage
+
+### Basic Usage
+
+```ruby
+require 'dry_validation_openapi'
+
+class CreateUserContract < Dry::Validation::Contract
+  extend DryValidationOpenapi::Convertable
+
+  params do
+    required(:email).value(:string)
+    required(:age).value(:integer)
+    optional(:name).value(:string)
+  end
+end
+
+# Generate OpenAPI schema
+schema = CreateUserContract.open_api_schema
+# => {
+#   type: :object,
+#   properties: {
+#     email: { type: :string },
+#     age: { type: :integer, format: 'int32' },
+#     name: { type: :string }
+#   },
+#   required: ['email', 'age']
+# }
+```
+
+### With rswag
+
+Use in your rswag request specs:
+
+```ruby
+# spec/requests/users_spec.rb
+require 'swagger_helper'
+
+RSpec.describe 'Users API' do
+  path '/users' do
+    post 'Creates a user' do
+      tags 'Users'
+      consumes 'application/json'
+
+      parameter name: :body,
+                in: :body,
+                required: true,
+                schema: CreateUserContract.open_api_schema
+
+      response '201', 'user created' do
+        let(:body) { { email: 'user@example.com', age: 25 } }
+        run_test!
+      end
+    end
+  end
+end
+```
+
+### Nested Objects
+
+```ruby
+class CreateOrderContract < Dry::Validation::Contract
+  extend DryValidationOpenapi::Convertable
+
+  params do
+    required(:order_id).value(:string)
+    required(:customer).hash do
+      required(:name).value(:string)
+      required(:email).value(:string)
+    end
+  end
+end
+
+CreateOrderContract.open_api_schema
+# => {
+#   type: :object,
+#   properties: {
+#     order_id: { type: :string },
+#     customer: {
+#       type: :object,
+#       properties: {
+#         name: { type: :string },
+#         email: { type: :string }
+#       },
+#       required: ['name', 'email']
+#     }
+#   },
+#   required: ['order_id', 'customer']
+# }
+```
+
+### Arrays of Objects
+
+```ruby
+class CreateInvoiceContract < Dry::Validation::Contract
+  extend DryValidationOpenapi::Convertable
+
+  params do
+    required(:issue_date).value(:time)
+    required(:line_items).array(:hash) do
+      required(:description).filled(:string)
+      required(:amount).filled(:decimal)
+    end
+  end
+end
+
+CreateInvoiceContract.open_api_schema
+# => {
+#   type: :object,
+#   properties: {
+#     issue_date: { type: :string, format: 'date-time' },
+#     line_items: {
+#       type: :array,
+#       items: {
+#         type: :object,
+#         properties: {
+#           description: { type: :string },
+#           amount: { type: :number, format: 'double' }
+#         },
+#         required: ['description', 'amount']
+#       }
+#     }
+#   },
+#   required: ['issue_date', 'line_items']
+# }
+```
+
+## Type Mappings
+
+| dry-validation type | OpenAPI type | OpenAPI format |
+|---------------------|--------------|----------------|
+| `:string`           | `string`     | -              |
+| `:integer`, `:int`  | `integer`    | `int32`        |
+| `:float`            | `number`     | `float`        |
+| `:decimal`, `:number` | `number`   | `double`       |
+| `:bool`, `:boolean` | `boolean`    | -              |
+| `:date`             | `string`     | `date`         |
+| `:time`, `:date_time` | `string`   | `date-time`    |
+| `:hash`             | `object`     | -              |
+| `:array`            | `array`      | -              |
+
+## How It Works
+
+This gem uses **static parsing** rather than runtime introspection:
+
+1. **Reads the contract file** as plain text using the contract's source location
+2. **Parses to AST** using Ruby's built-in Ripper parser
+3. **Walks the AST** to find the `params do...end` block
+4. **Extracts field definitions** (required/optional, names, types, nesting)
+5. **Converts to OpenAPI schema** format
+
+This approach is:
+- ✅ Fast and lightweight (no contract instantiation)
+- ✅ Simple to understand (just parsing Ruby code)
+- ✅ Works without dry-validation loaded
+- ⚠️ Cannot handle dynamically-generated contracts (rare in practice)
+
+## Development
+
+After checking out the repo, run:
+
+```bash
+bundle install
+```
+
+Run the tests:
+
+```bash
+bundle exec rspec
+```
+
+Build the gem:
+
+```bash
+gem build dry_validation_openapi.gemspec
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/troptropcontent/dry_validation_openapi.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Credits
+
+Created to solve the problem of maintaining duplicate schema definitions in dry-validation contracts and OpenAPI documentation.

data/lib/dry_validation_openapi/contract_parser.rb

@@ -0,0 +1,200 @@
+require 'ripper'
+
+module DryValidationOpenapi
+  class ContractParser
+    def self.parse_file(file_path)
+      source = File.read(file_path)
+      new(source).parse
+    end
+
+    def initialize(source)
+      @source = source
+      @schema_definitions = []
+    end
+
+    def parse
+      sexp = Ripper.sexp(@source)
+      find_params_block(sexp)
+      @schema_definitions
+    end
+
+    private
+
+    def find_params_block(node)
+      return unless node.is_a?(Array)
+
+      # Look for method_add_block with params
+      if node[0] == :method_add_block
+        method_call = node[1]
+        if method_call.is_a?(Array) && is_params_call?(method_call)
+          # Found the params block
+          do_block = node[2]
+          if do_block && do_block[0] == :do_block
+            extract_params_body(do_block)
+          end
+          return
+        end
+      end
+
+      # Recursively search
+      node.each { |child| find_params_block(child) }
+    end
+
+    def is_params_call?(node)
+      return false unless node.is_a?(Array)
+
+      case node[0]
+      when :method_add_arg
+        fcall = node[1]
+        return fcall.is_a?(Array) && fcall[0] == :fcall && fcall[1].is_a?(Array) && fcall[1][1] == 'params'
+      when :fcall
+        return node[1].is_a?(Array) && node[1][1] == 'params'
+      end
+
+      false
+    end
+
+    def extract_params_body(do_block)
+      # do_block structure: [:do_block, params, [:bodystmt, statements, ...]]
+      body = do_block[2]
+      return unless body && body[0] == :bodystmt
+
+      statements = body[1]
+      extract_statements(statements, depth: 0, parent: nil)
+    end
+
+    def extract_statements(statements, depth:, parent:)
+      return unless statements.is_a?(Array)
+
+      statements.each do |stmt|
+        case stmt[0]
+        when :method_add_arg, :call
+          # Simple field definition like required(:email).value(:string)
+          # or optional(:metadata).hash
+          field_info = parse_method_chain(stmt, depth: depth, parent: parent)
+          @schema_definitions << field_info if field_info
+        when :method_add_block
+          # Field with nested block like required(:settings).hash do...end
+          field_info = parse_method_chain(stmt[1], depth: depth, parent: parent, has_block: true)
+          if field_info
+            @schema_definitions << field_info
+
+            # Extract nested fields with this field as their parent
+            nested_block = stmt[2]
+            if nested_block && nested_block[0] == :do_block
+              nested_body = nested_block[2]
+              if nested_body && nested_body[0] == :bodystmt
+                extract_statements(nested_body[1], depth: depth + 1, parent: field_info[:name])
+              end
+            end
+          end
+        end
+      end
+    end
+
+    def parse_method_chain(node, depth:, parent:, has_block: false)
+      # Extract the base method (required/optional)
+      base_method = find_base_method(node)
+      return nil unless base_method && ['required', 'optional'].include?(base_method)
+
+      # Extract field name (symbol argument to required/optional)
+      field_name = find_field_name(node)
+      return nil unless field_name
+
+      # Extract type information (.value, .array, .hash, etc.)
+      type_info = find_type_info(node, has_block: has_block)
+
+      {
+        required: base_method == 'required',
+        name: field_name,
+        type: type_info[:type],
+        sub_type: type_info[:sub_type],
+        has_nested: type_info[:has_nested],
+        depth: depth,
+        parent: parent
+      }
+    end
+
+    def find_base_method(node)
+      return nil unless node.is_a?(Array)
+
+      case node[0]
+      when :method_add_arg, :call
+        return find_base_method(node[1])
+      when :fcall
+        ident = node[1]
+        return ident[1] if ident && ident[0] == :@ident
+      end
+
+      nil
+    end
+
+    def find_field_name(node)
+      symbols = find_all_symbols(node)
+      symbols.first  # The first symbol is the field name
+    end
+
+    def find_all_symbols(node, symbols = [])
+      return symbols unless node.is_a?(Array)
+
+      if node[0] == :symbol_literal
+        symbol_node = node[1]
+        if symbol_node && symbol_node[0] == :symbol
+          ident = symbol_node[1]
+          if ident && ident[0] == :@ident
+            symbols << ident[1]
+          end
+        end
+      end
+
+      node.each { |child| find_all_symbols(child, symbols) }
+      symbols
+    end
+
+    def find_type_info(node, has_block: false)
+      # Look for method calls like .value(:string), .filled(:string), .array(:string), .hash
+      type_method = find_type_method_name(node)
+
+      case type_method
+      when 'value', 'filled'
+        # Both .value() and .filled() take the same type argument
+        # .filled() additionally ensures the value is not nil/empty
+        symbols = find_all_symbols(node)
+        type_value = symbols[1]  # First symbol is field name, second is type
+        { type: type_value, sub_type: nil, has_nested: false }
+      when 'array'
+        symbols = find_all_symbols(node)
+        sub_type = symbols[1]  # Type of array items
+        { type: 'array', sub_type: sub_type, has_nested: has_block }
+      when 'hash'
+        { type: 'hash', sub_type: nil, has_nested: has_block }
+      else
+        # No type specified, default to string
+        { type: nil, sub_type: nil, has_nested: false }
+      end
+    end
+
+    def find_type_method_name(node)
+      return nil unless node.is_a?(Array)
+
+      case node[0]
+      when :call
+        # [:call, receiver, period, method_name]
+        method_name = node[3]
+        if method_name && method_name[0] == :@ident
+          return method_name[1]
+        end
+        # Continue searching in receiver
+        find_type_method_name(node[1])
+      when :method_add_arg
+        find_type_method_name(node[1])
+      else
+        node.each do |child|
+          result = find_type_method_name(child)
+          return result if result
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/dry_validation_openapi/convertable.rb

@@ -0,0 +1,41 @@
+module DryValidationOpenapi
+  # Module to extend dry-validation contracts with OpenAPI schema generation
+  #
+  # @example
+  #   class CreateUserContract < Dry::Validation::Contract
+  #     extend DryValidationOpenapi::Convertable
+  #
+  #     params do
+  #       required(:email).value(:string)
+  #       required(:age).value(:integer)
+  #     end
+  #   end
+  #
+  #   # In your rswag spec
+  #   parameter name: :body, in: :body, schema: CreateUserContract.open_api_schema
+  #
+  module Convertable
+    # Returns the file path where this contract class is defined
+    #
+    # @return [String] the absolute path to the contract file
+    def location
+      @location ||= Object.const_source_location(name)[0]
+    end
+
+    # Generates an OpenAPI schema from this contract's params block
+    #
+    # @return [Hash] OpenAPI schema hash with type, properties, and required fields
+    def open_api_schema
+      @open_api_schema ||= SchemaBuilder.build(location)
+    end
+
+    # Clears the cached schema, forcing regeneration on next access
+    # Useful during development or when contract definition changes
+    #
+    # @return [nil]
+    def clear_schema_cache!
+      @open_api_schema = nil
+      @location = nil
+    end
+  end
+end

data/lib/dry_validation_openapi/schema_builder.rb

@@ -0,0 +1,125 @@
+require_relative 'contract_parser'
+
+module DryValidationOpenapi
+  class SchemaBuilder
+    # Maps dry-validation types to OpenAPI type (and optionally format)
+    # See: https://swagger.io/specification/#data-types
+    TYPE_MAPPING = {
+      'string' => :string,
+      'integer' => { type: :integer, format: 'int32' },
+      'int' => { type: :integer, format: 'int32' },
+      'float' => { type: :number, format: 'float' },
+      'decimal' => { type: :number, format: 'double' },
+      'number' => { type: :number, format: 'double' },
+      'bool' => :boolean,
+      'boolean' => :boolean,
+      'date' => { type: :string, format: 'date' },
+      'time' => { type: :string, format: 'date-time' },
+      'date_time' => { type: :string, format: 'date-time' },
+      'array' => :array,
+      'hash' => :object
+    }.freeze
+
+    def self.build(contract_file_path)
+      new(contract_file_path).build
+    end
+
+    def initialize(contract_file_path)
+      @contract_file_path = contract_file_path
+      @definitions = []
+    end
+
+    def build
+      @definitions = ContractParser.parse_file(@contract_file_path)
+      build_schema(@definitions)
+    end
+
+    private
+
+    def build_schema(definitions, depth = 0, parent = nil)
+      schema = {
+        type: :object,
+        properties: {},
+        required: []
+      }
+
+      # Group definitions by depth and parent to handle nesting
+      current_level = definitions.select { |d| d[:depth] == depth && d[:parent] == parent }
+
+      current_level.each do |field|
+        property_schema = build_property_schema(field, definitions, depth)
+        schema[:properties][field[:name].to_sym] = property_schema
+        schema[:required] << field[:name] if field[:required]
+      end
+
+      # Clean up empty required array
+      schema.delete(:required) if schema[:required].empty?
+
+      schema
+    end
+
+    def build_property_schema(field, all_definitions, current_depth)
+      case field[:type]
+      when 'array'
+        build_array_schema(field, all_definitions, current_depth)
+      when 'hash'
+        build_hash_schema(field, all_definitions, current_depth)
+      else
+        build_simple_schema(field)
+      end
+    end
+
+    def build_simple_schema(field)
+      type_info = TYPE_MAPPING[field[:type]] || :string
+
+      # type_info can be either a symbol (:string) or a hash ({type: :integer, format: 'int32'})
+      if type_info.is_a?(Hash)
+        type_info.dup  # Return a copy to avoid modifying the frozen hash
+      else
+        { type: type_info }
+      end
+    end
+
+    def build_array_schema(field, all_definitions, current_depth)
+      schema = { type: :array }
+
+      if field[:has_nested]
+        # Array items have nested schema (e.g., array of objects with defined properties)
+        # Filter by both depth and parent to get only this array's nested fields
+        nested_fields = all_definitions.select { |d| d[:depth] == current_depth + 1 && d[:parent] == field[:name] }
+
+        if nested_fields.any?
+          # Build nested schema for array items
+          nested_schema = build_schema(all_definitions, current_depth + 1, field[:name])
+          schema[:items] = nested_schema
+        else
+          # Has nested block but no fields found - default to object
+          type_info = TYPE_MAPPING[field[:sub_type]] || :object
+          schema[:items] = type_info.is_a?(Hash) ? type_info.dup : { type: type_info }
+        end
+      elsif field[:sub_type]
+        # Simple array with specified item type
+        type_info = TYPE_MAPPING[field[:sub_type]] || :string
+        schema[:items] = type_info.is_a?(Hash) ? type_info.dup : { type: type_info }
+      end
+
+      schema
+    end
+
+    def build_hash_schema(field, all_definitions, current_depth)
+      if field[:has_nested]
+        # Find nested fields for this specific hash (filter by parent)
+        nested_fields = all_definitions.select { |d| d[:depth] == current_depth + 1 && d[:parent] == field[:name] }
+
+        if nested_fields.any?
+          # Build nested schema
+          nested_schema = build_schema(all_definitions, current_depth + 1, field[:name])
+          return nested_schema
+        end
+      end
+
+      # Empty hash or hash without nested definition
+      { type: :object }
+    end
+  end
+end

data/lib/dry_validation_openapi/version.rb

@@ -0,0 +1,3 @@
+module DryValidationOpenapi
+  VERSION = "0.1.0"
+end

data/lib/dry_validation_openapi.rb

@@ -0,0 +1,8 @@
+require_relative 'dry_validation_openapi/version'
+require_relative 'dry_validation_openapi/contract_parser'
+require_relative 'dry_validation_openapi/schema_builder'
+require_relative 'dry_validation_openapi/convertable'
+
+module DryValidationOpenapi
+  class Error < StandardError; end
+end

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification
+name: dry_validation_openapi
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- troptropcontent
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: dry-validation
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+description: Automatically convert dry-validation contract definitions to OpenAPI
+  3.0 schemas for use with rswag and other OpenAPI tools. Uses static parsing to extract
+  type information from contract params blocks.
+email:
+- troptropcontent@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/dry_validation_openapi.rb
+- lib/dry_validation_openapi/contract_parser.rb
+- lib/dry_validation_openapi/convertable.rb
+- lib/dry_validation_openapi/schema_builder.rb
+- lib/dry_validation_openapi/version.rb
+homepage: https://github.com/troptropcontent/dry_validation_openapi
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/troptropcontent/dry_validation_openapi
+  source_code_uri: https://github.com/troptropcontent/dry_validation_openapi
+  changelog_uri: https://github.com/troptropcontent/dry_validation_openapi/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Generate OpenAPI schemas from dry-validation contracts
+test_files: []