grape-oas 1.0.0

data/lib/grape_oas/exporter/oas2_schema.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require_relative "concerns/tag_builder"
+require_relative "concerns/schema_indexer"
+
+module GrapeOAS
+  module Exporter
+    class OAS2Schema
+      include Concerns::TagBuilder
+      include Concerns::SchemaIndexer
+
+      def initialize(api_model:)
+        @api = api_model
+        @ref_tracker = Set.new
+        @ref_schemas = {}
+      end
+
+      def generate
+        {
+          "swagger" => "2.0",
+          "info" => build_info,
+          "host" => build_host,
+          "basePath" => build_base_path,
+          "schemes" => build_schemes,
+          "consumes" => build_consumes,
+          "produces" => build_produces,
+          "tags" => build_tags,
+          "paths" => build_paths,
+          "definitions" => build_definitions,
+          "securityDefinitions" => build_security_definitions,
+          "security" => build_security
+        }.compact
+      end
+
+      private
+
+      def build_info
+        {
+          "title" => @api.title,
+          "version" => @api.version
+        }
+      end
+
+      def build_host
+        @api.host
+      end
+
+      def build_base_path
+        @api.base_path
+      end
+
+      def build_schemes
+        Array(@api.schemes).presence
+      end
+
+      def build_consumes
+        media_types = @api.paths.flat_map do |path|
+          path.operations.flat_map { |op| op.consumes || [] }
+        end.uniq
+
+        media_types.empty? ? [Constants::MimeTypes::JSON] : media_types
+      end
+
+      def build_produces
+        media_types = @api.paths.flat_map do |path|
+          path.operations.flat_map { |op| op.produces || [] }
+        end.uniq
+
+        media_types.empty? ? [Constants::MimeTypes::JSON] : media_types
+      end
+
+      def build_paths
+        OAS2::Paths.new(@api, @ref_tracker,
+                        suppress_default_error_response: @api.suppress_default_error_response,).build
+      end
+
+      def build_schema_or_ref(schema)
+        if schema.respond_to?(:canonical_name) && schema.canonical_name
+          ref_name = schema.canonical_name.gsub("::", "_")
+          @ref_tracker << schema.canonical_name
+          { "$ref" => "#/definitions/#{ref_name}" }
+        else
+          build_schema(schema)
+        end
+      end
+
+      def build_schema(schema)
+        OAS2::Schema.new(schema, @ref_tracker).build
+      end
+
+      def build_definitions
+        definitions = {}
+        pending = @ref_tracker.to_a
+        processed = Set.new
+
+        # Add pre-registered models to pending
+        Array(@api.registered_schemas).each do |schema|
+          pending << schema.canonical_name if schema.respond_to?(:canonical_name) && schema.canonical_name
+        end
+
+        until pending.empty?
+          canonical_name = pending.shift
+          next if processed.include?(canonical_name)
+
+          processed << canonical_name
+
+          ref_name = canonical_name.gsub("::", "_")
+          schema = find_schema_by_canonical_name(canonical_name)
+          definitions[ref_name] = OAS2::Schema.new(schema, @ref_tracker).build if schema
+          collect_refs(schema, pending) if schema
+
+          @ref_tracker.to_a.each do |cn|
+            pending << cn unless processed.include?(cn) || pending.include?(cn)
+          end
+        end
+
+        definitions
+      end
+
+      def build_security_definitions
+        return nil if @api.security_definitions.nil? || @api.security_definitions.empty?
+
+        @api.security_definitions
+      end
+
+      def build_security
+        return nil if @api.security.nil? || @api.security.empty?
+
+        @api.security
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module Exporter
+    module OAS3
+      # OAS3-specific Operation exporter
+      # Inherits common operation logic from Base::Operation
+      class Operation < Base::Operation
+        private
+
+        # OAS3-specific fields: parameters (no body), requestBody, responses
+        def build_version_specific_fields
+          nullable_keyword = @options.key?(:nullable_keyword) ? @options[:nullable_keyword] : true
+
+          {
+            "parameters" => Parameter.new(@op, @ref_tracker, nullable_keyword: nullable_keyword).build,
+            "requestBody" => RequestBody.new(@op.request_body, @ref_tracker, nullable_keyword: nullable_keyword).build,
+            "responses" => Response.new(@op.responses, @ref_tracker, nullable_keyword: nullable_keyword).build
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module Exporter
+    module OAS3
+      class Parameter
+        def initialize(operation, ref_tracker = nil, nullable_keyword: true)
+          @op = operation
+          @ref_tracker = ref_tracker
+          @nullable_keyword = nullable_keyword
+        end
+
+        def build
+          Array(@op.parameters).map do |param|
+            {
+              "name" => param.name,
+              "in" => param.location,
+              "required" => param.required,
+              "description" => param.description,
+              "schema" => Schema.new(param.schema, @ref_tracker, nullable_keyword: @nullable_keyword).build
+            }.compact
+          end.presence
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module Exporter
+    module OAS3
+      class RequestBody
+        def initialize(request_body, ref_tracker = nil, nullable_keyword: true)
+          @request_body = request_body
+          @ref_tracker = ref_tracker
+          @nullable_keyword = nullable_keyword
+        end
+
+        def build
+          return nil unless @request_body
+
+          data = {
+            "description" => @request_body.description,
+            "required" => @request_body.required,
+            "content" => build_content(@request_body.media_types)
+          }.compact
+
+          data.merge!(@request_body.extensions) if @request_body.extensions&.any?
+          data
+        end
+
+        private
+
+        def build_content(media_types)
+          return nil unless media_types
+
+          media_types.each_with_object({}) do |mt, h|
+            schema_entry = build_schema_or_ref(mt.schema)
+            entry = {
+              "schema" => schema_entry,
+              "examples" => mt.examples
+            }.compact
+            entry.merge!(mt.extensions) if mt.extensions&.any?
+            h[mt.mime_type] = entry
+          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" => "#/components/schemas/#{ref_name}" }
+          else
+            Schema.new(schema, @ref_tracker, nullable_keyword: @nullable_keyword).build
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module Exporter
+    module OAS3
+      class Response
+        def initialize(responses, ref_tracker = nil, nullable_keyword: true)
+          @responses = responses
+          @ref_tracker = ref_tracker
+          @nullable_keyword = nullable_keyword
+        end
+
+        def build
+          @responses.each_with_object({}) do |resp, h|
+            h[resp.http_status] = {
+              "description" => resp.description || "Response",
+              "headers" => build_headers(resp.headers),
+              "content" => build_content(resp.media_types, resp.examples)
+            }.compact
+            h[resp.http_status].merge!(resp.extensions) if resp.extensions
+          end
+        end
+
+        private
+
+        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
+
+            # OAS3 requires headers to have schema wrapper and optional description
+            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 = { "schema" => { "type" => schema_type } }
+            header_obj["description"] = description if description
+            h[name] = header_obj
+          end
+        end
+
+        def build_content(media_types, response_examples = nil)
+          return nil unless media_types
+
+          media_types.each_with_object({}) do |mt, h|
+            entry = { "schema" => build_schema_or_ref(mt.schema) }
+            # OAS3: use "example" for single value, "examples" for named examples with value wrapper
+            # Media type examples take precedence over response-level examples
+            examples = mt.examples || response_examples
+            add_examples_to_entry(entry, examples)
+            h[mt.mime_type] = entry.compact
+          end
+        end
+
+        # OAS3 examples must be wrapped as { name => { "value" => ... } }
+        # Use "example" (singular) for simple cases, "examples" for multiple/named
+        def add_examples_to_entry(entry, examples)
+          return unless examples
+
+          if examples.is_a?(Hash) && examples.keys.all? { |k| k.is_a?(String) || k.is_a?(Symbol) }
+            # Named examples - wrap each value if not already wrapped
+            entry["examples"] = examples.transform_values do |v|
+              v.is_a?(Hash) && v.key?("value") ? v : { "value" => v }
+            end
+          else
+            # Single example value
+            entry["example"] = examples
+          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" => "#/components/schemas/#{ref_name}" }
+          else
+            Schema.new(schema, @ref_tracker, nullable_keyword: @nullable_keyword).build
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module Exporter
+    module OAS3
+      class Schema
+        def initialize(schema, ref_tracker = nil, nullable_keyword: true)
+          @schema = schema
+          @ref_tracker = ref_tracker
+          @nullable_keyword = nullable_keyword
+        end
+
+        def build
+          return {} unless @schema
+          return build_all_of_schema if @schema.all_of && !@schema.all_of.empty?
+          return build_one_of_schema if @schema.one_of && !@schema.one_of.empty?
+          return build_any_of_schema if @schema.any_of && !@schema.any_of.empty?
+
+          schema_hash = build_base_hash
+          apply_examples(schema_hash)
+          sanitize_enum_against_type(schema_hash)
+          apply_extensions_and_extra_properties(schema_hash)
+          apply_all_constraints(schema_hash)
+          schema_hash.compact
+        end
+
+        def build_base_hash
+          schema_hash = {}
+          schema_hash["type"] = nullable_type
+          schema_hash["format"] = @schema.format
+          schema_hash["description"] = @schema.description.to_s if @schema.description
+          props = build_properties(@schema.properties)
+          schema_hash["properties"] = props if props
+          schema_hash["items"] = @schema.items ? build_schema_or_ref(@schema.items) : nil
+          schema_hash["required"] = @schema.required if @schema.required && !@schema.required.empty?
+          schema_hash["enum"] = normalize_enum(@schema.enum, schema_hash["type"]) if @schema.enum
+          schema_hash
+        end
+
+        def apply_examples(schema_hash)
+          return unless @schema.examples
+
+          examples = Array(@schema.examples).map { |ex| coerce_example(ex, schema_hash["type"]) }
+          schema_hash["example"] = examples.first
+        end
+
+        def apply_extensions_and_extra_properties(schema_hash)
+          schema_hash.merge!(@schema.extensions) if @schema.extensions
+          schema_hash.delete("properties") if schema_hash["properties"]&.empty? || @schema.type != Constants::SchemaTypes::OBJECT
+          schema_hash["additionalProperties"] = @schema.additional_properties unless @schema.additional_properties.nil?
+          if !@nullable_keyword && !@schema.unevaluated_properties.nil?
+            schema_hash["unevaluatedProperties"] = @schema.unevaluated_properties
+          end
+          schema_hash["$defs"] = @schema.defs if !@nullable_keyword && @schema.defs && !@schema.defs.empty?
+          schema_hash["discriminator"] = build_discriminator if @schema.discriminator
+        end
+
+        def apply_all_constraints(schema_hash)
+          apply_numeric_constraints(schema_hash)
+          apply_string_constraints(schema_hash)
+          apply_array_constraints(schema_hash)
+        end
+
+        private
+
+        # 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
+
+        # Build oneOf schema for polymorphism
+        def build_one_of_schema
+          one_of_items = @schema.one_of.map do |item|
+            build_schema_or_ref(item)
+          end
+
+          result = { "oneOf" => one_of_items }
+          result["description"] = @schema.description.to_s if @schema.description
+          result["discriminator"] = build_discriminator if @schema.discriminator
+          result
+        end
+
+        # Build anyOf schema for polymorphism
+        def build_any_of_schema
+          any_of_items = @schema.any_of.map do |item|
+            build_schema_or_ref(item)
+          end
+
+          result = { "anyOf" => any_of_items }
+          result["description"] = @schema.description.to_s if @schema.description
+          result["discriminator"] = build_discriminator if @schema.discriminator
+          result
+        end
+
+        # Build OAS3 discriminator object
+        def build_discriminator
+          return nil unless @schema.discriminator
+
+          if @schema.discriminator.is_a?(Hash)
+            # Already in object format with propertyName and optional mapping
+            disc = { "propertyName" => @schema.discriminator[:property_name] || @schema.discriminator["propertyName"] }
+            mapping = @schema.discriminator[:mapping] || @schema.discriminator["mapping"]
+            disc["mapping"] = mapping if mapping && !mapping.empty?
+            disc
+          else
+            # Simple string - convert to object format
+            { "propertyName" => @schema.discriminator.to_s }
+          end
+        end
+
+        def nullable_type
+          return @schema.type unless @schema.respond_to?(:nullable) && @schema.nullable
+
+          if @nullable_keyword
+            # OAS3.0 style
+            type_hash = { "type" => @schema.type, "nullable" => true }
+            return type_hash["type"] if @schema.type.nil?
+            return type_hash["type"] if @schema.type.is_a?(Array)
+
+            type_hash["type"]
+          else
+            base = Array(@schema.type || Constants::SchemaTypes::STRING)
+            (base | ["null"])
+          end
+        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" => "#/components/schemas/#{ref_name}" }
+          else
+            Schema.new(schema, @ref_tracker, nullable_keyword: @nullable_keyword).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
+
+          result = coerced.uniq
+          return nil if result.empty?
+
+          result
+        end
+
+        def apply_numeric_constraints(hash)
+          hash["minimum"] = @schema.minimum if @schema.minimum
+          hash["maximum"] = @schema.maximum if @schema.maximum
+
+          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
+              hash["exclusiveMinimum"] = @schema.minimum
+              hash.delete("minimum")
+            end
+            if @schema.exclusive_maximum && @schema.maximum
+              hash["exclusiveMaximum"] = @schema.maximum
+              hash.delete("maximum")
+            end
+          end
+        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["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
+        end
+
+        # Ensure enum values match the declared type; drop enum if incompatible to avoid invalid specs
+        def sanitize_enum_against_type(hash)
+          enum_vals = hash["enum"]
+          type_val = hash["type"]
+          return unless enum_vals && type_val
+
+          base_type = if type_val.is_a?(Array)
+                        (type_val - ["null"]).first
+                      else
+                        type_val
+                      end
+
+          # Remove enum for unsupported base types or mismatches
+          case base_type
+          when Constants::SchemaTypes::ARRAY, Constants::SchemaTypes::OBJECT, nil
+            hash.delete("enum")
+          when Constants::SchemaTypes::INTEGER
+            hash.delete("enum") unless enum_vals.all? { |v| v.is_a?(Integer) }
+          when Constants::SchemaTypes::NUMBER
+            hash.delete("enum") unless enum_vals.all? { |v| v.is_a?(Numeric) }
+          when Constants::SchemaTypes::BOOLEAN
+            hash.delete("enum") unless enum_vals.all? { |v| [true, false].include?(v) }
+          else # string and fallback
+            hash.delete("enum") unless enum_vals.all? { |v| v.is_a?(String) }
+          end
+        end
+
+        def coerce_example(example, type_val)
+          base_type = if type_val.is_a?(Array)
+                        (type_val - ["null"]).first
+                      else
+                        type_val
+                      end
+
+          case base_type
+          when Constants::SchemaTypes::INTEGER
+            example.to_i
+          when Constants::SchemaTypes::NUMBER
+            example.to_f
+          when Constants::SchemaTypes::BOOLEAN
+            example == true || example.to_s == "true"
+          when Constants::SchemaTypes::STRING, nil
+            example.to_s
+          else
+            example
+          end
+        end
+      end
+    end
+  end
+end

data/lib/grape_oas/exporter/oas30_schema.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module Exporter
+    class OAS30Schema < OAS3Schema
+      private
+
+      def openapi_version
+        "3.0.0"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module Exporter
+    module OAS31
+      # OAS3.1-specific Schema exporter
+      # Differs from OAS3 by preferring `examples` over deprecated `example`.
+      class Schema < OAS3::Schema
+        def openapi_version
+          "3.1.0"
+        end
+
+        def build
+          hash = super
+
+          # swap example -> examples if present
+          if hash.key?("example")
+            ex = hash.delete("example")
+            hash["examples"] ||= ex
+          end
+          normalize_examples!(hash)
+          hash
+        end
+
+        private
+
+        # Ensure examples is always an array and recurse into nested schemas
+        def normalize_examples!(hash)
+          hash["examples"] = [hash["examples"]].compact if hash.key?("examples") && !hash["examples"].is_a?(Array)
+
+          if hash.key?("properties") && hash["properties"].is_a?(Hash)
+            hash["properties"].each_value { |v| normalize_examples!(v) if v.is_a?(Hash) }
+          end
+
+          return unless hash.key?("items") && hash["items"].is_a?(Hash)
+
+          normalize_examples!(hash["items"])
+        end
+      end
+    end
+  end
+end

data/lib/grape_oas/exporter/oas31_schema.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module Exporter
+    class OAS31Schema < OAS3Schema
+      private
+
+      def openapi_version
+        "3.1.0"
+      end
+
+      def build_info
+        info = super
+        license = if @api.respond_to?(:license) && @api.license
+                    @api.license
+                  else
+                    # OAS 3.1 requires exactly one of 'identifier' OR 'url' (not both)
+                    { "name" => Constants::Defaults::LICENSE_NAME,
+                      "identifier" => Constants::Defaults::LICENSE_IDENTIFIER }
+                  end
+        info["license"] = license
+        info
+      end
+
+      def schema_builder
+        OAS31::Schema
+      end
+
+      def nullable_keyword?
+        false
+      end
+    end
+  end
+end