grape-oas 1.0.0

data/lib/grape_oas/exporter/base/operation.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module Exporter
+    module Base
+      # Base class for Operation exporters
+      # Contains common logic shared between OAS2 and OAS3
+      class Operation
+        def initialize(operation, ref_tracker = nil, **options)
+          @op = operation
+          @ref_tracker = ref_tracker
+          @options = options
+        end
+
+        def build
+          data = build_common_fields
+
+          # Add version-specific fields
+          data.merge!(build_version_specific_fields)
+
+          # Add security if present
+          data["security"] = @op.security unless @op.security.nil? || @op.security.empty?
+
+          # Guarantee a 4xx response for lint rules
+          ensure_default_error_response(data)
+
+          # Merge extensions
+          data.merge!(@op.extensions) if @op.extensions&.any?
+
+          data.compact
+        end
+
+        private
+
+        # Common fields present in both OAS2 and OAS3
+        def build_common_fields
+          summary = @op.summary
+          summary ||= @op.description&.split(/\.\s/)&.first&.strip
+          # Fallback: generate a readable summary from the operationId to satisfy lint rules
+          if summary.nil? && @op.operation_id
+            summary = @op.operation_id
+                         .to_s
+                         .tr("_", " ")
+                         .split
+                         .map(&:capitalize)
+                         .join(" ")
+          end
+
+          {
+            "operationId" => @op.operation_id,
+            "summary" => summary,
+            "description" => @op.description,
+            "deprecated" => @op.deprecated,
+            "tags" => @op.tag_names
+          }
+        end
+
+        # Template method - subclasses must implement version-specific fields
+        # @return [Hash] Version-specific fields (e.g., consumes/produces for OAS2, requestBody for OAS3)
+        def build_version_specific_fields
+          raise NotImplementedError, "#{self.class} must implement #build_version_specific_fields"
+        end
+
+        # Ensure there is at least one 4xx response when any responses exist
+        # Can be suppressed per-operation via suppress_default_error_response flag
+        def ensure_default_error_response(data)
+          # Check operation-level suppression
+          return data if @op.respond_to?(:suppress_default_error_response) && @op.suppress_default_error_response
+
+          # Check global suppression
+          return data if @options[:suppress_default_error_response]
+
+          responses = data["responses"]
+          return data unless responses && !responses.empty?
+
+          has_4xx = responses.keys.any? { |code| code.to_s.start_with?("4") }
+          return data if has_4xx
+
+          responses["400"] = {
+            "description" => "Bad Request"
+          }
+
+          data
+        end
+      end
+    end
+  end
+end

data/lib/grape_oas/exporter/base/paths.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module Exporter
+    module Base
+      # Base class for Paths exporters
+      # Contains common logic shared between OAS2 and OAS3
+      class Paths
+        def initialize(source, ref_tracker = nil, **options)
+          @source = source
+          @ref_tracker = ref_tracker
+          @options = options
+        end
+
+        def build
+          if api?(@source)
+            build_paths(@source)
+          else
+            build_path_item(@source)
+          end
+        end
+
+        private
+
+        def api?(obj)
+          obj.respond_to?(:paths)
+        end
+
+        def build_paths(api)
+          paths = {}
+          api.paths.each do |path|
+            paths[path.template] = build_path_item(path)
+          end
+          paths
+        end
+
+        def build_path_item(path)
+          item = {}
+          path.operations.each do |operation|
+            item[operation.http_method] = build_operation(operation)
+          end
+          item
+        end
+
+        # Template method - subclasses must implement
+        # Returns the version-specific Operation instance
+        def build_operation(operation)
+          raise NotImplementedError, "#{self.class} must implement #build_operation"
+        end
+      end
+    end
+  end
+end

data/lib/grape_oas/exporter/concerns/schema_indexer.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module Exporter
+    module Concerns
+      # Shared schema indexing and reference collection logic for OAS2 and OAS3 schema exporters.
+      # Handles building schema indexes from operations and collecting nested schema references.
+      module SchemaIndexer
+        def find_schema_by_canonical_name(canonical_name)
+          @ref_schemas[canonical_name] || schema_index[canonical_name]
+        end
+
+        def schema_index
+          @schema_index ||= build_schema_index
+        end
+
+        def build_schema_index
+          index = {}
+          # Index schemas from operations
+          @api.paths.each do |path|
+            path.operations.each do |op|
+              collect_schemas_from_operation(op, index)
+            end
+          end
+          # Index pre-registered models
+          Array(@api.registered_schemas).each do |schema|
+            index_schema(schema, index)
+          end
+          index
+        end
+
+        def collect_schemas_from_operation(operation, index)
+          Array(operation.parameters).each do |param|
+            index_schema(param.schema, index)
+          end
+
+          if operation.request_body
+            Array(operation.request_body.media_types).each do |media_type|
+              index_schema(media_type.schema, index)
+            end
+          end
+
+          Array(operation.responses).each do |resp|
+            Array(resp.media_types).each do |media_type|
+              index_schema(media_type.schema, index)
+            end
+          end
+        end
+
+        def index_schema(schema, index)
+          return unless schema.respond_to?(:canonical_name) && schema.canonical_name
+
+          index[schema.canonical_name] ||= schema
+        end
+
+        def collect_refs(schema, pending, seen = Set.new)
+          return unless schema
+
+          if schema.respond_to?(:canonical_name) && schema.canonical_name
+            return if seen.include?(schema.canonical_name)
+
+            seen << schema.canonical_name
+            @ref_schemas[schema.canonical_name] ||= schema
+          end
+
+          if schema.respond_to?(:properties) && schema.properties
+            schema.properties.each_value do |prop|
+              if prop.respond_to?(:canonical_name) && prop.canonical_name
+                pending << prop.canonical_name
+                @ref_schemas[prop.canonical_name] ||= prop
+              end
+              collect_refs(prop, pending, seen)
+            end
+          end
+          collect_refs(schema.items, pending, seen) if schema.respond_to?(:items) && schema.items
+
+          # Handle allOf/oneOf/anyOf composition (for inheritance/polymorphism)
+          %i[all_of one_of any_of].each do |composition_type|
+            next unless schema.respond_to?(composition_type) && schema.send(composition_type)
+
+            schema.send(composition_type).each do |sub_schema|
+              if sub_schema.respond_to?(:canonical_name) && sub_schema.canonical_name
+                pending << sub_schema.canonical_name
+                @ref_schemas[sub_schema.canonical_name] ||= sub_schema
+              end
+              collect_refs(sub_schema, pending, seen)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/grape_oas/exporter/concerns/tag_builder.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module Exporter
+    module Concerns
+      # Shared tag-building logic for OAS2 and OAS3 schema exporters.
+      # Extracts tag definitions from operations and normalizes tag formats.
+      module TagBuilder
+        def build_tags
+          used_tag_names = collect_used_tag_names
+          seen_names = Set.new
+          tags = Array(@api.tag_defs).filter_map do |tag|
+            normalized = normalize_tag(tag)
+            tag_name = normalized["name"]
+            # Only include tags that are actually used by operations and not already seen
+            next if seen_names.include?(tag_name) || !used_tag_names.include?(tag_name)
+
+            seen_names << tag_name
+            normalized
+          end
+          tags.empty? ? nil : tags
+        end
+
+        def normalize_tag(tag)
+          if tag.is_a?(Hash)
+            # Convert symbol keys to string keys
+            tag.transform_keys(&:to_s)
+          elsif tag.respond_to?(:name)
+            h = { "name" => tag.name.to_s }
+            h["description"] = tag.description if tag.respond_to?(:description)
+            h
+          else
+            name = tag.to_s
+            desc = if defined?(ActiveSupport::Inflector)
+                     "Operations about #{ActiveSupport::Inflector.pluralize(name)}"
+                   else
+                     "Operations about #{name}s"
+                   end
+            { "name" => name, "description" => desc }
+          end
+        end
+
+        def collect_used_tag_names
+          used_tags = Set.new
+          @api.paths.each do |path|
+            path.operations.each do |op|
+              Array(op.tag_names).each { |t| used_tags << t }
+            end
+          end
+          used_tags
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module Exporter
+    module OAS2
+      # OAS2-specific Operation exporter
+      # Inherits common operation logic from Base::Operation
+      class Operation < Base::Operation
+        private
+
+        # OAS2-specific fields: consumes, produces, parameters (including body)
+        def build_version_specific_fields
+          {
+            "consumes" => consumes,
+            "produces" => produces,
+            "parameters" => Parameter.new(@op, @ref_tracker).build,
+            "responses" => Response.new(@op.responses, @ref_tracker).build
+          }
+        end
+
+        def consumes
+          Array(@op.consumes.presence || [Constants::MimeTypes::JSON])
+        end
+
+        def produces
+          Array(@op.produces.presence || [Constants::MimeTypes::JSON])
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module Exporter
+    module OAS2
+      class Parameter
+        PRIMITIVE_MAPPINGS = {
+          Constants::SchemaTypes::INTEGER => { type: Constants::SchemaTypes::INTEGER, format: "int32" },
+          "long" => { type: Constants::SchemaTypes::INTEGER, format: "int64" },
+          "float" => { type: Constants::SchemaTypes::NUMBER, format: "float" },
+          "double" => { type: Constants::SchemaTypes::NUMBER, format: "double" },
+          "byte" => { type: Constants::SchemaTypes::STRING, format: "byte" },
+          "date" => { type: Constants::SchemaTypes::STRING, format: "date" },
+          "dateTime" => { type: Constants::SchemaTypes::STRING, format: "date-time" },
+          "binary" => { type: Constants::SchemaTypes::STRING, format: "binary" },
+          "password" => { type: Constants::SchemaTypes::STRING, format: "password" },
+          "email" => { type: Constants::SchemaTypes::STRING, format: "email" },
+          "uuid" => { type: Constants::SchemaTypes::STRING, format: "uuid" }
+        }.freeze
+
+        def initialize(operation, ref_tracker = nil)
+          @op = operation
+          @ref_tracker = ref_tracker
+        end
+
+        def build
+          params = Array(@op.parameters).map { |param| build_parameter(param) }
+          params << build_body_parameter(@op.request_body) if @op.request_body
+          params
+        end
+
+        private
+
+        def build_parameter(param)
+          type = param.schema&.type
+          format = param.schema&.format
+          primitive_types = PRIMITIVE_MAPPINGS.keys + %w[object string boolean file json array]
+          is_primitive = type && primitive_types.include?(type)
+
+          if is_primitive && param.location != "body"
+            mapping = PRIMITIVE_MAPPINGS[type]
+            result = {
+              "name" => param.name,
+              "in" => param.location,
+              "required" => param.required,
+              "description" => param.description,
+              "type" => mapping ? mapping[:type] : type,
+              "format" => format || (mapping ? mapping[:format] : nil)
+            }
+            apply_collection_format(result, param, type)
+            result.compact
+          else
+            {
+              "name" => param.name,
+              "in" => param.location,
+              "required" => param.required,
+              "description" => param.description,
+              "schema" => build_schema_or_ref(param.schema)
+            }.tap do |h|
+              h["type"] = type if type
+              h["format"] = format if format
+            end.compact
+          end
+        end
+
+        def apply_collection_format(result, param, type)
+          return unless type == Constants::SchemaTypes::ARRAY
+          return unless param.collection_format
+
+          valid_formats = %w[csv ssv tsv pipes multi brackets]
+          result["collectionFormat"] = param.collection_format if valid_formats.include?(param.collection_format)
+        end
+
+        def build_body_parameter(request_body)
+          schema = build_body_schema(request_body)
+          name = derive_body_name(request_body)
+          {
+            "name" => name,
+            "in" => "body",
+            "required" => request_body.required,
+            "description" => request_body.description,
+            "schema" => schema
+          }.compact
+        end
+
+        def derive_body_name(request_body)
+          # Use explicit body_name if provided
+          return request_body.body_name if request_body.respond_to?(:body_name) && request_body.body_name
+
+          # Fall back to canonical name from schema
+          canonical = begin
+            request_body&.media_types&.first&.schema&.canonical_name
+          rescue NoMethodError
+            nil
+          end
+          canonical ? canonical.gsub("::", "_") : "body"
+        end
+
+        def build_body_schema(request_body)
+          mt = Array(request_body.media_types).first
+          mt ? build_schema_or_ref(mt.schema) : nil
+        end
+
+        def build_schema_or_ref(schema)
+          if schema.respond_to?(:canonical_name) && schema.canonical_name
+            @ref_tracker << schema.canonical_name if @ref_tracker
+            ref_name = schema.canonical_name.gsub("::", "_")
+            { "$ref" => "#/definitions/#{ref_name}" }
+          else
+            Schema.new(schema, @ref_tracker).build
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module Exporter
+    module OAS2
+      # OAS2-specific Paths exporter
+      # Inherits common path building logic from Base::Paths
+      class Paths < Base::Paths
+        private
+
+        # Build OAS2-specific operation
+        def build_operation(operation)
+          Operation.new(operation, @ref_tracker,
+                        suppress_default_error_response: @options[:suppress_default_error_response],).build
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module Exporter
+    module OAS2
+      class Response
+        def initialize(responses, ref_tracker = nil)
+          @responses = responses
+          @ref_tracker = ref_tracker
+        end
+
+        def build
+          res = {}
+          Array(@responses).each do |resp|
+            res[resp.http_status] = {
+              "description" => resp.description,
+              "schema" => build_response_schema(resp),
+              "headers" => build_headers(resp.headers),
+              "examples" => build_examples(resp.media_types, resp.examples)
+            }.compact
+            res[resp.http_status].merge!(resp.extensions) if resp.extensions
+          end
+          res
+        end
+
+        private
+
+        def build_response_schema(resp)
+          mt = Array(resp.media_types).first
+          mt ? build_schema_or_ref(mt.schema) : nil
+        end
+
+        def build_schema_or_ref(schema)
+          if schema.respond_to?(:canonical_name) && schema.canonical_name
+            @ref_tracker << schema.canonical_name if @ref_tracker
+            ref_name = schema.canonical_name.gsub("::", "_")
+            { "$ref" => "#/definitions/#{ref_name}" }
+          else
+            Schema.new(schema, @ref_tracker).build
+          end
+        end
+
+        def build_headers(headers)
+          return nil unless headers && !headers.empty?
+
+          headers.each_with_object({}) do |hdr, h|
+            name = hdr[:name] || hdr["name"] || hdr[:key] || hdr["key"]
+            next unless name
+
+            # OAS2 headers have type at top level (not wrapped in schema)
+            schema_value = hdr[:schema] || hdr["schema"] || {}
+            schema_type = schema_value["type"] || schema_value[:type] || Constants::SchemaTypes::STRING
+            description = hdr[:description] || hdr["description"] || schema_value["description"]
+
+            header_obj = { "type" => schema_type }
+            header_obj["description"] = description if description
+            h[name] = header_obj
+          end
+        end
+
+        def build_examples(media_types, response_examples = nil)
+          return nil unless media_types
+
+          mt = Array(media_types).first
+          # Media type examples take precedence over response-level examples
+          examples = mt&.examples || response_examples
+          return nil unless examples
+
+          examples.is_a?(Hash) ? examples : { mt&.mime_type || "application/json" => examples }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module Exporter
+    module OAS2
+      class Schema
+        def initialize(schema, ref_tracker = nil)
+          @schema = schema
+          @ref_tracker = ref_tracker
+        end
+
+        def build
+          return {} unless @schema
+
+          # Handle allOf composition (for inheritance)
+          return build_all_of_schema if @schema.all_of && !@schema.all_of.empty?
+
+          # Handle oneOf/anyOf by using first type (OAS2 doesn't support oneOf/anyOf)
+          # Skip if schema has explicit type - use type with extensions instead
+          return build_first_of_schema(:one_of) if @schema.one_of && !@schema.one_of.empty? && !@schema.type
+          return build_first_of_schema(:any_of) if @schema.any_of && !@schema.any_of.empty? && !@schema.type
+
+          schema_hash = build_base_hash
+          apply_constraints(schema_hash)
+          apply_extensions(schema_hash)
+          schema_hash.compact
+        end
+
+        def build_base_hash
+          schema_hash = {
+            "type" => @schema.type,
+            "format" => @schema.format,
+            "description" => @schema.description&.to_s,
+            "properties" => build_properties(@schema.properties),
+            "items" => (@schema.items ? build_schema_or_ref(@schema.items) : nil),
+            "enum" => normalize_enum(@schema.enum, @schema.type)
+          }
+          if schema_hash["properties"].nil? || schema_hash["properties"].empty? || @schema.type != Constants::SchemaTypes::OBJECT
+            schema_hash.delete("properties")
+          end
+          schema_hash["example"] = @schema.examples if @schema.examples
+          schema_hash["required"] = @schema.required if @schema.required && !@schema.required.empty?
+          schema_hash["discriminator"] = @schema.discriminator if @schema.discriminator
+          schema_hash
+        end
+
+        def apply_constraints(schema_hash)
+          schema_hash["minLength"] = @schema.min_length if @schema.min_length
+          schema_hash["maxLength"] = @schema.max_length if @schema.max_length
+          schema_hash["pattern"] = @schema.pattern if @schema.pattern
+          schema_hash["minimum"] = @schema.minimum if @schema.minimum
+          schema_hash["maximum"] = @schema.maximum if @schema.maximum
+          schema_hash["exclusiveMinimum"] = @schema.exclusive_minimum if @schema.exclusive_minimum
+          schema_hash["exclusiveMaximum"] = @schema.exclusive_maximum if @schema.exclusive_maximum
+          schema_hash["minItems"] = @schema.min_items if @schema.min_items
+          schema_hash["maxItems"] = @schema.max_items if @schema.max_items
+        end
+
+        def apply_extensions(schema_hash)
+          schema_hash.merge!(@schema.extensions) if @schema.extensions
+        end
+
+        private
+
+        # Build schema from oneOf/anyOf by using first type (OAS2 doesn't support these)
+        # Extensions are merged to allow x-anyOf/x-oneOf for consumers that support them
+        def build_first_of_schema(composition_type)
+          schemas = @schema.send(composition_type)
+          first_schema = schemas.first
+          return {} unless first_schema
+
+          # Build the first schema as the fallback
+          result = build_schema_or_ref(first_schema)
+          result["description"] = @schema.description.to_s if @schema.description
+          apply_extensions(result)
+          result
+        end
+
+        # Build allOf schema for inheritance
+        def build_all_of_schema
+          all_of_items = @schema.all_of.map do |item|
+            build_schema_or_ref(item)
+          end
+
+          result = { "allOf" => all_of_items }
+          result["description"] = @schema.description.to_s if @schema.description
+          result
+        end
+
+        def build_properties(properties)
+          return nil unless properties
+          return nil if properties.empty?
+
+          properties.transform_values do |prop_schema|
+            build_schema_or_ref(prop_schema)
+          end
+        end
+
+        def build_schema_or_ref(schema)
+          if schema.respond_to?(:canonical_name) && schema.canonical_name
+            @ref_tracker << schema.canonical_name if @ref_tracker
+            ref_name = schema.canonical_name.gsub("::", "_")
+            { "$ref" => "#/definitions/#{ref_name}" }
+          else
+            Schema.new(schema, @ref_tracker).build
+          end
+        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
+
+          coerced.uniq
+        end
+      end
+    end
+  end
+end