grape_openapi3 0.1.2 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b766639dad295072af7561e8f833b1324b40cf8fbe3dd541f50b28f584b776a
-  data.tar.gz: ae90d2dfa58d2b6de7739fb4da1133b6e6e1bdbee54c9be6446de073989de9c2
+  metadata.gz: 78e04b539409184f39938ed214a2a3b0840278df89caa2e996b53398aa0cb6da
+  data.tar.gz: '08cf3d2c3cb9741e74dddd315df30c6b6d268ad70835d7c9ca9c1f5028e45fcb'
 SHA512:
-  metadata.gz: ceffb4098ee59dc64bf447603126f56ec62a422abec5c525aa48fc45fe71c2c30f7ab4eb276a9ba30fba1a46cfbc6a6317ebdad332b649d55c310ebd65b3105f
-  data.tar.gz: d74161cb5c277c94bb578a2dadc54ab5878586fd44e51de024242375a5f1840212b25d83bc8746e0bb06199e86d5112f6150b5c295032a9cba29d0f61a23e573
+  metadata.gz: 13666a9f3bbab86c2cbcd4e8972a5ade583a09a10e471dfdf3301fc8a3ce374e1341a64190f1aa90d2fea4d13b0eb887dfb0e8910252838e9a495e1d155ba052
+  data.tar.gz: 4ccecbac4a3a0a6843da4819657a9a1bd8f3a6697517c860278a7d8cd9ecea8201120c65f39e683107e1bf67a770875f74907d059425932562c883c14f63e8f5

data/lib/grape_openapi3/builders/operation_builder.rb

@@ -81,8 +81,13 @@ module GrapeOpenapi3
         entity = @route[:success_entity]
         return { "description" => "Success" } unless entity
 
-        # Unpack hash form: { code: 201, message: "Created", model: ProductEntity }
-        description, entity_class = unpack_success(entity)
+        # Unpack hash form: { code: 201, message: "Created", model: ProductEntity, schema: {...} }
+        description, entity_class, inline_schema = unpack_success(entity)
+
+        if inline_schema
+          media = @route[:produces].first || "application/json"
+          return { "description" => description, "content" => { media => { "schema" => inline_schema } } }
+        end
 
         unless entity_class
           return { "description" => description }
@@ -98,19 +103,20 @@ module GrapeOpenapi3
         { "description" => description, "content" => { media => { "schema" => schema } } }
       end
 
-      # Returns [description_string, entity_class_or_nil].
-      # Accepts both the bare-class form and the hash form.
+      # Returns [description_string, entity_class_or_nil, inline_schema_or_nil].
+      # Accepts the bare-class form, the hash form with :model, and the hash form with :schema.
       def unpack_success(entity)
         if entity.is_a?(Class)
-          return ["Success", entity]
+          return ["Success", entity, nil]
         end
 
-        return ["Success", nil] unless entity.is_a?(Hash)
+        return ["Success", nil, nil] unless entity.is_a?(Hash)
 
-        message = entity[:message] || entity["message"] || "Success"
-        model   = entity[:model]   || entity["model"]
-        klass   = model.is_a?(Class) ? model : nil
-        [message, klass]
+        message       = entity[:message] || entity["message"] || "Success"
+        model         = entity[:model]   || entity["model"]
+        inline_schema = entity[:schema]  || entity["schema"]
+        klass         = model.is_a?(Class) ? model : nil
+        [message, klass, inline_schema]
       end
     end
   end

data/lib/grape_openapi3/builders/parameter_builder.rb

@@ -4,15 +4,21 @@ module GrapeOpenapi3
   module Builders
     # Converts a route's params hash into OpenAPI 3.0 `parameters` + `requestBody`.
     #
-    # Param location is determined in this priority order:
+    # Param location is determined (per top-level param) in this priority order:
     #   1. Explicit: documentation: { param_type: "path|query|header|body|formData" }
     #   2. Name matches a {segment} in the path → path
     #   3. type: File → formData (multipart)
     #   4. HTTP method GET/DELETE → query
     #   5. HTTP method POST/PUT/PATCH → body (requestBody JSON)
     #
-    # Params marked as formData OR containing a File field produce a
-    # multipart/form-data requestBody. All other body params produce JSON.
+    # Nested params:
+    #   Grape flattens nested params into bracketed keys, e.g.
+    #     "address"        => { type: "Hash" }
+    #     "address[street]"=> { type: "String", required: true }
+    #     "tags"           => { type: "Array" }
+    #     "tags[label]"    => { type: "String" }
+    #   These are reassembled into nested object / array-of-object schemas in the
+    #   request body. Location is decided by the TOP-LEVEL key; children inherit it.
     class ParameterBuilder
       BODY_METHODS = %w[post put patch].freeze
       PATH_SEGMENT = /\{(\w+)\}/
@@ -29,22 +35,20 @@ module GrapeOpenapi3
       end
 
       def call
-        inline   = []  # path / query / header params
-        json     = {}  # body params → application/json requestBody
-        formdata = {}  # formData params → multipart/form-data requestBody
+        inline   = []  # path / query / header params (flat)
+        json     = {}  # body params (full bracket keys) → application/json
+        formdata = {}  # formData params → multipart/form-data
 
-        @route[:params].each do |name, definition|
-          name_s = name.to_s.sub(/\[\]$/, "")  # strip Grape's array brackets
-          defn   = definition.is_a?(Hash) ? definition : {}
-          loc    = location(name_s, defn)
+        grouped_by_top.each do |top, info|
+          loc = location(top, info[:root] || {})
 
           case loc
           when :path, :query, :header
-            inline << build_parameter(name_s, defn, loc)
+            inline << build_parameter(top, info[:root] || {}, loc)
           when :form
-            formdata[name_s] = defn
+            formdata.merge!(info[:entries])
           when :body
-            json[name_s] = defn
+            json.merge!(info[:entries])
           end
         end
 
@@ -56,6 +60,27 @@ module GrapeOpenapi3
 
       private
 
+      # Group every param entry under its top-level name, keeping the full bracket
+      # keys so the body schema can be rebuilt with nesting.
+      def grouped_by_top
+        @route[:params].each_with_object({}) do |(name, definition), acc|
+          key      = name.to_s
+          segments = bracket_segments(key)
+          top      = segments.first
+          next if top.nil? || top.empty?
+
+          defn = definition.is_a?(Hash) ? definition : {}
+          acc[top] ||= { entries: {}, root: nil }
+          acc[top][:entries][key] = defn
+          acc[top][:root] = defn if segments.length == 1
+        end
+      end
+
+      # "address[street]" → ["address", "street"]; "tags[]" → ["tags"]; "id" → ["id"]
+      def bracket_segments(key)
+        key.scan(/[^\[\]]+/)
+      end
+
       def location(name, defn)
         # Path segments are structural — they always win over any explicit hint.
         return :path if @path_names.include?(name)
@@ -83,9 +108,7 @@ module GrapeOpenapi3
       end
 
       def build_parameter(name, defn, loc)
-        schema = TypeMapper.call(defn[:type] || String)
-        schema["enum"]    = Array(defn[:values]) if defn[:values]
-        schema["default"] = defn[:default]       unless defn[:default].nil?
+        schema = leaf_schema(defn, nullable: false)
 
         param = {
           "name"     => name,
@@ -103,39 +126,92 @@ module GrapeOpenapi3
       def build_request_body(json, formdata)
         return nil if json.empty? && formdata.empty?
 
-        all = formdata.merge(json)
-
         if formdata.any?
-          build_body("multipart/form-data", all)
+          build_body("multipart/form-data", formdata.merge(json))
         else
-          build_body("application/json", all)
+          build_body("application/json", json)
         end
       end
 
-      def build_body(media_type, params)
+      # Build the requestBody object from flat bracket-keyed entries, rebuilding
+      # nested objects and arrays-of-objects along the way.
+      def build_body(media_type, entries)
+        schema = object_schema_from(entries)
+        {
+          "required" => Array(schema["required"]).any?,
+          "content"  => { media_type => { "schema" => schema } },
+        }
+      end
+
+      # --- nested schema assembly -----------------------------------------
+
+      def object_schema_from(entries)
+        root = { children: {}, defn: nil }
+
+        entries.each do |key, defn|
+          node = root
+          bracket_segments(key).each do |seg|
+            node[:children][seg] ||= { children: {}, defn: nil }
+            node = node[:children][seg]
+          end
+          node[:defn] = defn
+        end
+
+        node_to_schema(root)
+      end
+
+      def node_to_schema(node)
+        return leaf_schema(node[:defn] || {}) if node[:children].empty?
+
+        object = build_object(node[:children])
+        array_container?(node[:defn]) ? wrap_array(object, node[:defn]) : decorate(object, node[:defn])
+      end
+
+      def build_object(children)
         properties = {}
         required   = []
 
-        params.each do |name, defn|
-          schema = TypeMapper.call(defn[:type] || String)
-          schema["enum"]     = Array(defn[:values]) if defn[:values]
-          schema["default"]  = defn[:default]       unless defn[:default].nil?
-          schema["nullable"] = true                 unless defn[:required]
+        children.each do |name, child|
+          properties[name] = node_to_schema(child)
+          required << name if child[:defn] && child[:defn][:required]
+        end
 
-          desc = defn[:desc] || defn[:description]
-          schema["description"] = desc.to_s if desc
+        schema = { "type" => "object", "properties" => properties }
+        schema["required"] = required unless required.empty?
+        schema
+      end
 
-          properties[name] = schema
-          required << name if defn[:required]
-        end
+      def wrap_array(items_schema, defn)
+        decorate({ "type" => "array", "items" => items_schema }, defn)
+      end
 
-        obj_schema = { "type" => "object", "properties" => properties }
-        obj_schema["required"] = required unless required.empty?
+      def array_container?(defn)
+        return false unless defn
 
-        {
-          "required" => required.any?,
-          "content"  => { media_type => { "schema" => obj_schema } },
-        }
+        name = defn[:type].is_a?(Class) ? defn[:type].name.to_s : defn[:type].to_s
+        name == "Array" || name.match?(/\A\[.*\]\z/)
+      end
+
+      # A scalar/terminal param: map its type and attach enum/default/desc/nullable.
+      def leaf_schema(defn, nullable: nil)
+        schema = TypeMapper.call(defn[:type] || String)
+        decorate(schema, defn, nullable: nullable)
+      end
+
+      # Attach enum/default/description and (for body params) nullable when optional.
+      def decorate(schema, defn, nullable: nil)
+        return schema unless defn
+
+        schema["enum"]    = Array(defn[:values]) if defn[:values]
+        schema["default"] = defn[:default]       unless defn[:default].nil?
+
+        desc = defn[:desc] || defn[:description]
+        schema["description"] = desc.to_s if desc
+
+        nullable = !defn[:required] if nullable.nil?
+        schema["nullable"] = true if nullable
+
+        schema
       end
     end
   end

data/lib/grape_openapi3/config.rb

@@ -1,5 +1,17 @@
 # frozen_string_literal: true
 
 module GrapeOpenapi3
-  Config = Struct.new(:info, :servers, :security_schemes, :security, :tags, keyword_init: true)
-end
+  # Configuration object passed through the document build.
+  #
+  # schema_name_separator: joins namespace segments when two entities share the
+  #   same short name (e.g. V2::Mentors::MenteeResponse vs V2::Kids::MenteeResponse
+  #   become "Mentors_MenteeResponse" / "Kids_MenteeResponse"). Default "_".
+  Config = Struct.new(
+    :info, :servers, :security_schemes, :security, :tags, :schema_name_separator,
+    keyword_init: true
+  ) do
+    def schema_name_separator
+      self[:schema_name_separator] || "_"
+    end
+  end
+end

data/lib/grape_openapi3/document.rb

@@ -15,12 +15,15 @@ module GrapeOpenapi3
     end
 
     def build
-      entity_reader = Readers::EntityReader.new
+      entity_reader = Readers::EntityReader.new(separator: @config.schema_name_separator)
 
       route_list = @app.routes
         .map  { |r| Readers::RouteReader.call(r) }
         .compact
 
+      # Pre-scan all reachable entities so schema names are stable and collision-free.
+      entity_reader.prepare(route_list.flat_map { |rd| success_entity_classes(rd) })
+
       paths      = build_paths(route_list, entity_reader)
       components = build_components(entity_reader)
 
@@ -39,6 +42,18 @@ module GrapeOpenapi3
 
     private
 
+    # The Grape::Entity class(es) referenced by a route's success response, if any.
+    # Handles both the bare-class form and the hash form ({ model: SomeEntity }).
+    def success_entity_classes(route_data)
+      entity = route_data[:success_entity]
+      klass  = if entity.is_a?(Class)
+                 entity
+               elsif entity.is_a?(Hash)
+                 entity[:model] || entity["model"]
+               end
+      klass.is_a?(Class) ? [klass] : []
+    end
+
     def build_paths(route_list, entity_reader)
       route_list.each_with_object({}) do |route_data, paths|
         path   = route_data[:path]

data/lib/grape_openapi3/readers/entity_reader.rb

@@ -9,17 +9,36 @@ module GrapeOpenapi3
     #   - Circular references are broken (placeholder set before recursing)
     #   - Nested entities (using: SomeEntity) become $ref pointers
     #
+    # Schema naming (collision-free):
+    #   By default each schema is named after the entity's last namespace segment
+    #   (e.g. "MenteeResponse"). When two DIFFERENT entity classes share that short
+    #   name, #prepare disambiguates them deterministically using the shortest
+    #   namespace suffix that makes them unique (e.g. "Mentors_MenteeResponse" vs
+    #   "Kids_MenteeResponse"). Names are stable regardless of registration order.
+    #
     # Usage:
-    #   reader = EntityReader.new
-    #   name = reader.register(MyEntity)   # → "MyEntity", adds to schemas
-    #   reader.schemas                     # → { "MyEntity" => { ... } }
+    #   reader = EntityReader.new(separator: "_")
+    #   reader.prepare([RootEntityA, RootEntityB])  # optional but recommended
+    #   name = reader.register(MyEntity)            # → schema name, adds to schemas
+    #   reader.schemas                              # → { "MyEntity" => { ... } }
     class EntityReader
       REPRESENT_EXPOSURE = "Grape::Entity::Exposure::RepresentExposure"
 
       attr_reader :schemas
 
-      def initialize
-        @schemas = {}
+      def initialize(separator: "_")
+        @schemas   = {}
+        @separator = separator
+        @name_map  = {} # full Ruby class name => assigned schema name
+      end
+
+      # Walk the entity graph reachable from the given root entities and assign a
+      # stable, collision-free schema name to every entity. Call before #register.
+      def prepare(root_entities)
+        all = []
+        Array(root_entities).each { |e| collect(resolve_class(e), all) }
+        @name_map = build_name_map(all)
+        self
       end
 
       # Register an entity class and return its schema name.
@@ -38,6 +57,57 @@ module GrapeOpenapi3
 
       private
 
+      # --- name assignment -------------------------------------------------
+
+      def collect(entity_class, acc)
+        return unless entity_class.respond_to?(:root_exposures)
+        return if acc.include?(entity_class)
+
+        acc << entity_class
+        entity_class.root_exposures.each do |exposure|
+          next unless represent_exposure?(exposure)
+
+          nested = resolve_class(exposure.using_class_name)
+          collect(nested, acc) if nested
+        end
+      end
+
+      def build_name_map(classes)
+        map = {}
+        classes.group_by { |c| short_name(c) }.each_value do |group|
+          if group.size == 1
+            map[group.first.name] = short_name(group.first)
+          else
+            disambiguate(group).each { |full, name| map[full] = name }
+          end
+        end
+        map
+      end
+
+      # Pick the shortest trailing namespace suffix that makes every class in the
+      # colliding group unique. Deterministic — depends only on class names.
+      def disambiguate(group)
+        parts = group.to_h { |c| [c.name, c.name.to_s.split("::")] }
+        depth = 2
+        loop do
+          names = parts.transform_values { |segs| segs.last(depth).join(@separator) }
+          break names if names.values.uniq.size == names.size
+          break names if parts.values.all? { |segs| segs.size <= depth }
+
+          depth += 1
+        end
+      end
+
+      def short_name(entity_class)
+        entity_class.name.to_s.split("::").last
+      end
+
+      def schema_name(entity_class)
+        @name_map[entity_class.name] || short_name(entity_class)
+      end
+
+      # --- schema building -------------------------------------------------
+
       def build_schema(entity_class)
         properties = {}
         required   = []
@@ -46,12 +116,14 @@ module GrapeOpenapi3
           key = exposure.key(nil).to_s
           doc = exposure.documentation || {}
 
-          prop = build_property(exposure, doc)
+          prop     = build_property(exposure, doc)
+          ref_like = prop.key?("$ref")
 
           # OpenAPI 3.0: $ref cannot have sibling properties — wrap in allOf
-          if prop.key?("$ref") && (!doc[:desc].nil? || doc[:nullable])
-            prop = { "allOf" => [prop] }
-          end
+          prop = { "allOf" => [prop] } if ref_like && (!doc[:desc].nil? || doc[:nullable])
+
+          # enum/format/example/min/max only apply to value schemas, never to $refs
+          apply_keywords(prop, doc) unless ref_like
 
           prop["description"] = doc[:desc].to_s unless doc[:desc].nil?
           prop["nullable"]    = true             if doc[:nullable]
@@ -65,6 +137,38 @@ module GrapeOpenapi3
         schema
       end
 
+      # Attach OpenAPI value keywords from the entity's documentation hash.
+      #   enum (or values), format, minimum, maximum → the scalar schema
+      #     (the array's items when it's an array of scalars, otherwise the prop)
+      #   default, example → the property itself
+      def apply_keywords(prop, doc)
+        scalar = scalar_target(prop)
+        enum   = doc[:enum] || doc[:values]
+
+        if scalar
+          scalar["enum"]    = Array(enum)       if enum
+          scalar["format"]  = doc[:format].to_s if doc[:format]
+          scalar["minimum"] = doc[:minimum]     unless doc[:minimum].nil?
+          scalar["maximum"] = doc[:maximum]     unless doc[:maximum].nil?
+        end
+
+        prop["default"] = doc[:default] unless doc[:default].nil?
+        prop["example"] = doc[:example] unless doc[:example].nil?
+      end
+
+      # The schema that scalar keywords belong to, or nil when there is none
+      # (e.g. an array of $refs). For an array of scalars it is the `items` schema.
+      def scalar_target(prop)
+        return nil if prop.key?("$ref") || prop.key?("allOf")
+
+        if prop["type"] == "array"
+          items = prop["items"]
+          items.is_a?(Hash) && !items.key?("$ref") ? items : nil
+        else
+          prop
+        end
+      end
+
       def build_property(exposure, doc)
         if represent_exposure?(exposure)
           nested_class = resolve_class(exposure.using_class_name)
@@ -87,10 +191,6 @@ module GrapeOpenapi3
       rescue NameError
         nil
       end
-
-      def schema_name(entity_class)
-        entity_class.name.to_s.split("::").last
-      end
     end
   end
 end

data/lib/grape_openapi3/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module GrapeOpenapi3
-  VERSION = "0.1.2"
+  VERSION = "0.1.4"
 end

data/lib/grape_openapi3.rb

@@ -44,13 +44,15 @@ module GrapeOpenapi3
     #     },
     #     security: [{ "Bearer" => [] }]
     #   )
-    def generate(app, info:, servers: [], security_schemes: {}, security: [], tags: [])
+    def generate(app, info:, servers: [], security_schemes: {}, security: [], tags: [],
+                 schema_name_separator: "_")
       config = Config.new(
-        info:             info,
-        servers:          servers,
-        security_schemes: security_schemes,
-        security:         security,
-        tags:             tags,
+        info:                  info,
+        servers:               servers,
+        security_schemes:      security_schemes,
+        security:              security,
+        tags:                  tags,
+        schema_name_separator: schema_name_separator,
       )
       Document.build(app, config)
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: grape_openapi3
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.4
 platform: ruby
 authors:
 - rodrigonbarreto
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-15 00:00:00.000000000 Z
+date: 2026-06-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: grape