grape-oas 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a578224c8df0f07ef5151db8496a084a64c6000f1f4c4158d7cc21efee1f91f
-  data.tar.gz: a1427ab277998cd7828e24c91f2555be6ea41b254312f14c4ad40b43204fa13c
+  metadata.gz: 54679fa806e8eae3cbff18605ccd3dd7e188e7a2cf774d92ea233172fefc94ef
+  data.tar.gz: ee59342a9d6c9be4bb79cf081beaaf833fae65bdfbaf12b619765eb37d1119a8
 SHA512:
-  metadata.gz: c03fa30c214a62b2f3164ced48ff16e6c8ba120126ac3d7397db0cd0a7e6ee191224b10bd59badb91f848d3bfcded18cc03e4da331f883c80203795dfa0a143b
-  data.tar.gz: b232aa12c2211dc35853933ad09e1d1d5451d1df9fc3c2e1cb2c3bc1d58f8769b892141381323669c3c158e6ca409bbab3358012f9be0360f2736cb6194b1ada
+  metadata.gz: 21f0ab789f3812daa0fa3971d2bb9ad9693351ee2178c1a2ac9c3f3e706f51023c1bf67bdb220098a74af19cd3eb90c42521a8bdc9992ef7af8594089e58c897
+  data.tar.gz: b6eef41e2c1eac91c3c41aa4e225f55a7650908d64133ec816e1e2c7bb3461282146020e6a181cc30156b85d11259ea2ae3aee50184e8b471420dbf0cd7df2ec

data/CHANGELOG.md

@@ -5,6 +5,17 @@ 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).
 
+
+## [1.0.1] - 2025-12-15
+
+### Fixes
+
+- [#8](https://github.com/numbata/grape-oas/pull/8): Add OAS2 parameter schema constraint export with enum normalization and retain zero-valued constraints across OAS exporters. - [@numbata](https://github.com/numbata).
+- [#9](https://github.com/numbata/grape-oas/pull/9): Treat GET/HEAD/DELETE as bodyless by default via shared constants and tests - [@numbata](https://github.com/numbata).
+- [#10](https://github.com/numbata/grape-oas/pull/10): Add grape-swagger compatible `in:` location syntax for parameters alongside `param_type` - [@numbata](https://github.com/numbata).
+- [#11](https://github.com/numbata/grape-oas/pull/11): Flatten nested Hash params to bracket-notation query params for GET/HEAD/DELETE requests - [@numbata](https://github.com/numbata).
+- [#12](https://github.com/numbata/grape-oas/pull/12): Add fallback to `spec[:desc]` for parameter descriptions when `documentation[:desc]` is not set - [@numbata](https://github.com/numbata).
+
 ## [1.0.0] - 2025-12-06
 
 ### Added

data/RELEASING.md

@@ -80,7 +80,7 @@ git push origin main
 
 This task will:
 - Bump the patch version in `lib/grape_oas/version.rb`
-- Ensure CHANGELOG.md has an "Unreleased" section
+- Ensure CHANGELOG.md has an "Unreleased" section with "* Your contribution here" placeholder
 - Commit the changes with message "Prepare for next development iteration"
 
 **Note**: The task is idempotent - safe to run multiple times without duplicating work.
@@ -89,7 +89,7 @@ This task will:
 <summary>Manual Post-Release Steps (if needed)</summary>
 
 1. **Prepare for next development cycle**:
-   - Add "Unreleased" section to CHANGELOG.md
+   - Add "Unreleased" section to CHANGELOG.md with "* Your contribution here" placeholder
    - Bump version in `lib/grape_oas/version.rb`
 
 2. **Commit post-release changes**:

data/grape-oas.gemspec

@@ -14,14 +14,18 @@ Gem::Specification.new do |spec|
   spec.license = "MIT"
   spec.required_ruby_version = ">= 3.2"
 
-  spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = spec.homepage
-  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata = {
+    "homepage_uri" => spec.homepage,
+    "source_code_uri" => spec.homepage,
+    "github_repo" => "https://github.com/numbata/grape-oas",
+    "changelog_uri" => "#{spec.homepage}/blob/main/CHANGELOG.md",
+    "documentation_uri" => "#{spec.homepage}#readme",
+    "bug_tracker_uri" => "#{spec.homepage}/issues",
+    "rubygems_mfa_required" => "true",
+  }
 
   spec.files = Dir["lib/**/*", "*.md", "LICENSE.txt", "grape-oas.gemspec"]
 
   spec.add_dependency "grape", ">= 3.0"
   spec.add_dependency "zeitwerk"
-
-  spec.metadata["rubygems_mfa_required"] = "true"
 end

data/lib/grape_oas/api_model_builders/request.rb

@@ -36,7 +36,7 @@ module GrapeOAS
         # OAS spec says GET/HEAD/DELETE "MAY ignore" request bodies
         # Skip by default unless explicitly allowed via documentation option
         http_method = operation.http_method.to_s.downcase
-        if %w[get head delete].include?(http_method)
+        if Constants::HttpMethods::BODYLESS_HTTP_METHODS.include?(http_method)
           allow_body = route.options.dig(:documentation, :request_body) ||
                        route.options[:request_body]
           return unless allow_body

data/lib/grape_oas/api_model_builders/request_params.rb

@@ -71,17 +71,34 @@ module GrapeOAS
       end
 
       # Extracts non-body params (path, query, header) from flat params.
+      # For non-body HTTP methods (GET, HEAD, DELETE), also includes nested params
+      # as flat query parameters with bracket notation (e.g., "tax_id[type]"),
+      # unless request_body is explicitly enabled.
       def extract_non_body_params(all_params, route_params)
         params = []
+        http_method = route.request_method.to_s.downcase
+        flatten_nested = should_flatten_nested_to_query?(http_method, all_params)
 
         all_params.each do |name, spec|
-          # Skip nested params (they go into body)
-          next if name.include?("[")
-          # Skip Hash/body params
-          next if location_resolver.body_param?(spec)
           # Skip hidden params
           next if location_resolver.hidden_parameter?(spec)
 
+          is_nested = name.include?("[")
+          is_hash_param = location_resolver.body_param?(spec)
+
+          # For nested bracket params (e.g., "tax_id[type]"), include as query params
+          # for non-body HTTP methods (unless request_body is explicitly enabled)
+          if is_nested
+            next unless flatten_nested
+
+            params << build_parameter(name, "query", spec[:required] || false, schema_builder.build(spec), spec)
+            next
+          end
+
+          # Skip Hash type params (they're handled via nested bracket params above
+          # or via body schema for POST/PUT/PATCH)
+          next if is_hash_param
+
           location = location_resolver.resolve(
             name: name,
             spec: spec,
@@ -97,13 +114,35 @@ module GrapeOAS
         params
       end
 
+      # Determines whether nested params should be flattened to query params.
+      # Returns true for GET/HEAD/DELETE unless body is explicitly requested via:
+      # - route-level `request_body: true` option
+      # - any parameter with `documentation: { in: 'body' }` or `documentation: { param_type: 'body' }`
+      def should_flatten_nested_to_query?(http_method, all_params)
+        return false unless Constants::HttpMethods::BODYLESS_HTTP_METHODS.include?(http_method)
+
+        # If request_body is explicitly enabled at route level, use body schema
+        return false if route.options.dig(:documentation, :request_body) || route.options[:request_body]
+
+        # If any parameter is explicitly marked as body, use body schema
+        has_explicit_body_param = all_params.any? do |name, spec|
+          next false if name.include?("[") # Skip bracket params, check parent Hash params only
+
+          param_type = spec.dig(:documentation, :param_type)&.to_s&.downcase
+          in_location = spec.dig(:documentation, :in)&.to_s&.downcase
+          param_type == "body" || in_location == "body"
+        end
+
+        !has_explicit_body_param
+      end
+
       def build_parameter(name, location, required, schema, spec)
         ApiModel::Parameter.new(
           location: location,
           name: name,
           required: required,
           schema: schema,
-          description: spec[:documentation]&.dig(:desc),
+          description: spec[:documentation]&.dig(:desc) || spec[:desc],
           collection_format: extract_collection_format(spec),
         )
       end

data/lib/grape_oas/api_model_builders/request_params_support/param_location_resolver.rb

@@ -19,20 +19,28 @@ module GrapeOAS
         end
 
         # Checks if a parameter should be in the request body.
+        # Supports both `param_type: 'body'` and `in: 'body'` for grape-swagger compatibility.
         #
         # @param spec [Hash] the parameter specification
         # @return [Boolean] true if it's a body parameter
         def self.body_param?(spec)
-          spec.dig(:documentation, :param_type) == "body" || [Hash, "Hash"].include?(spec[:type])
+          param_type = spec.dig(:documentation, :param_type)&.to_s&.downcase
+          in_location = spec.dig(:documentation, :in)&.to_s&.downcase
+
+          param_type == "body" || in_location == "body" || [Hash, "Hash"].include?(spec[:type])
         end
 
         # Checks if a parameter is explicitly marked as NOT a body param.
+        # Supports both `param_type` and `in` for grape-swagger compatibility.
         #
         # @param spec [Hash] the parameter specification
         # @return [Boolean] true if explicitly non-body
         def self.explicit_non_body_param?(spec)
           param_type = spec.dig(:documentation, :param_type)&.to_s&.downcase
-          param_type && %w[query header path].include?(param_type)
+          in_location = spec.dig(:documentation, :in)&.to_s&.downcase
+          location = param_type || in_location
+
+          location && %w[query header path].include?(location)
         end
 
         # Checks if a parameter should be hidden from documentation.
@@ -51,11 +59,29 @@ module GrapeOAS
         class << self
           private
 
+          # Extracts the parameter location from the specification.
+          # Supports both `param_type` and `in` options for grape-swagger compatibility.
+          #
+          # Precedence (highest to lowest):
+          #   1. `param_type` option (e.g., `documentation: { param_type: 'query' }`)
+          #   2. `in` option (e.g., `documentation: { in: 'query' }`)
+          #   3. Falls back to "query" if neither is specified
+          #
+          # Note: If both `param_type` and `in` are specified, `param_type` takes precedence.
+          # For example, `{ param_type: 'query', in: 'body' }` will be treated as query.
+          #
+          # @param spec [Hash] the parameter specification
+          # @param route [Object] the Grape route object
+          # @return [String] the parameter location
           def extract_from_spec(spec, route)
             # If body_name is set on the route, treat non-path params as body by default
-            return "body" if route.options[:body_name] && !spec.dig(:documentation, :param_type)
+            param_type = spec.dig(:documentation, :param_type)
+            in_location = spec.dig(:documentation, :in)
+            return "body" if route.options[:body_name] && !param_type && !in_location
 
-            spec.dig(:documentation, :param_type)&.downcase || "query"
+            # Support both param_type and in for grape-swagger compatibility
+            # param_type takes precedence over in when both are specified
+            (param_type || in_location)&.to_s&.downcase || "query"
           end
         end
       end

data/lib/grape_oas/constants.rb

@@ -16,6 +16,15 @@ module GrapeOAS
       ALL = [STRING, INTEGER, NUMBER, BOOLEAN, OBJECT, ARRAY, FILE].freeze
     end
 
+    # HTTP method-related constants
+    module HttpMethods
+      # HTTP methods that typically don't have request bodies.
+      # Per RFC 7231, GET/HEAD/DELETE semantics don't define body behavior,
+      # but many implementations ignore them. These are treated specially
+      # when generating OpenAPI specs.
+      BODYLESS_HTTP_METHODS = %w[get head delete].freeze
+    end
+
     # Common MIME types
     module MimeTypes
       JSON = "application/json"

data/lib/grape_oas/exporter/oas2/parameter.rb

@@ -34,7 +34,7 @@ module GrapeOAS
         def build_parameter(param)
           type = param.schema&.type
           format = param.schema&.format
-          primitive_types = PRIMITIVE_MAPPINGS.keys + %w[object string boolean file json array]
+          primitive_types = PRIMITIVE_MAPPINGS.keys + %w[object string boolean file json array number]
           is_primitive = type && primitive_types.include?(type)
 
           if is_primitive && param.location != "body"
@@ -47,6 +47,7 @@ module GrapeOAS
               "type" => mapping ? mapping[:type] : type,
               "format" => format || (mapping ? mapping[:format] : nil)
             }
+            apply_schema_constraints(result, param.schema)
             apply_collection_format(result, param, type)
             result.compact
           else
@@ -63,6 +64,38 @@ module GrapeOAS
           end
         end
 
+        def apply_schema_constraints(result, schema)
+          return unless schema
+
+          result["minimum"] = schema.minimum if schema.respond_to?(:minimum) && !schema.minimum.nil?
+          result["maximum"] = schema.maximum if schema.respond_to?(:maximum) && !schema.maximum.nil?
+          result["exclusiveMinimum"] = schema.exclusive_minimum if schema.respond_to?(:exclusive_minimum) && schema.exclusive_minimum
+          result["exclusiveMaximum"] = schema.exclusive_maximum if schema.respond_to?(:exclusive_maximum) && schema.exclusive_maximum
+          result["minLength"] = schema.min_length if schema.respond_to?(:min_length) && !schema.min_length.nil?
+          result["maxLength"] = schema.max_length if schema.respond_to?(:max_length) && !schema.max_length.nil?
+          result["minItems"] = schema.min_items if schema.respond_to?(:min_items) && !schema.min_items.nil?
+          result["maxItems"] = schema.max_items if schema.respond_to?(:max_items) && !schema.max_items.nil?
+          result["pattern"] = schema.pattern if schema.respond_to?(:pattern) && schema.pattern
+          result["enum"] = normalize_enum(schema.enum, result["type"]) if schema.respond_to?(:enum) && schema.enum
+        end
+
+        def normalize_enum(enum_vals, type)
+          return nil unless enum_vals.is_a?(Array)
+
+          coerced = enum_vals.map do |v|
+            case type
+            when Constants::SchemaTypes::INTEGER then v.to_i if v.respond_to?(:to_i)
+            when Constants::SchemaTypes::NUMBER then v.to_f if v.respond_to?(:to_f)
+            else v
+            end
+          end.compact
+
+          result = coerced.uniq
+          return nil if result.empty?
+
+          result
+        end
+
         def apply_collection_format(result, param, type)
           return unless type == Constants::SchemaTypes::ARRAY
           return unless param.collection_format

data/lib/grape_oas/exporter/oas3/schema.rb

@@ -167,18 +167,18 @@ module GrapeOAS
         end
 
         def apply_numeric_constraints(hash)
-          hash["minimum"] = @schema.minimum if @schema.minimum
-          hash["maximum"] = @schema.maximum if @schema.maximum
+          hash["minimum"] = @schema.minimum unless @schema.minimum.nil?
+          hash["maximum"] = @schema.maximum unless @schema.maximum.nil?
 
           if @nullable_keyword
             hash["exclusiveMinimum"] = @schema.exclusive_minimum if @schema.exclusive_minimum
             hash["exclusiveMaximum"] = @schema.exclusive_maximum if @schema.exclusive_maximum
           else
-            if @schema.exclusive_minimum && @schema.minimum
+            if @schema.exclusive_minimum && !@schema.minimum.nil?
               hash["exclusiveMinimum"] = @schema.minimum
               hash.delete("minimum")
             end
-            if @schema.exclusive_maximum && @schema.maximum
+            if @schema.exclusive_maximum && !@schema.maximum.nil?
               hash["exclusiveMaximum"] = @schema.maximum
               hash.delete("maximum")
             end
@@ -186,14 +186,14 @@ module GrapeOAS
         end
 
         def apply_string_constraints(hash)
-          hash["minLength"] = @schema.min_length if @schema.min_length
-          hash["maxLength"] = @schema.max_length if @schema.max_length
+          hash["minLength"] = @schema.min_length unless @schema.min_length.nil?
+          hash["maxLength"] = @schema.max_length unless @schema.max_length.nil?
           hash["pattern"] = @schema.pattern if @schema.pattern
         end
 
         def apply_array_constraints(hash)
-          hash["minItems"] = @schema.min_items if @schema.min_items
-          hash["maxItems"] = @schema.max_items if @schema.max_items
+          hash["minItems"] = @schema.min_items unless @schema.min_items.nil?
+          hash["maxItems"] = @schema.max_items unless @schema.max_items.nil?
         end
 
         # Ensure enum values match the declared type; drop enum if incompatible to avoid invalid specs

data/lib/grape_oas/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module GrapeOAS
-  VERSION = "1.0.0"
+  VERSION = "1.0.1"
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: grape-oas
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Andrei Subbota
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2025-12-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: grape
@@ -130,8 +131,12 @@ licenses:
 metadata:
   homepage_uri: https://github.com/numbata/grape-oas
   source_code_uri: https://github.com/numbata/grape-oas
+  github_repo: https://github.com/numbata/grape-oas
   changelog_uri: https://github.com/numbata/grape-oas/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/numbata/grape-oas#readme
+  bug_tracker_uri: https://github.com/numbata/grape-oas/issues
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -146,7 +151,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.8
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: OpenAPI (Swagger) v2 and v3 documentation for Grape APIs
 test_files: []