grape-oas 1.0.0

data/lib/grape_oas/api_model_builders/response.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module ApiModelBuilders
+    class Response
+      include Concerns::ContentTypeResolver
+      include Concerns::OasUtilities
+
+      # Default response parsers in priority order
+      # DocumentationResponsesParser has highest priority (most comprehensive)
+      # HttpCodesParser handles legacy grape-swagger formats
+      # DefaultResponseParser is the fallback
+      DEFAULT_PARSERS = [
+        ResponseParsers::DocumentationResponsesParser,
+        ResponseParsers::HttpCodesParser,
+        ResponseParsers::DefaultResponseParser
+      ].freeze
+
+      class << self
+        attr_writer :parsers
+
+        def parsers
+          @parsers ||= DEFAULT_PARSERS.dup
+        end
+
+        def reset_parsers!
+          @parsers = DEFAULT_PARSERS.dup
+        end
+      end
+
+      attr_reader :api, :route, :app
+
+      def initialize(api:, route:, app: nil)
+        @api = api
+        @route = route
+        @app = app
+      end
+
+      def build
+        specs = response_specs
+        grouped = group_specs_by_status(specs)
+        grouped.map { |_code, group_specs| build_response_from_group(group_specs) }
+      end
+
+      private
+
+      # Use Strategy pattern to parse responses
+      # Parsers are tried in order of priority
+      def response_specs
+        parser = parsers.find { |p| p.applicable?(route) }
+        parser ? parser.parse(route) : []
+      end
+
+      def parsers
+        @parsers ||= self.class.parsers.map(&:new)
+      end
+
+      # Groups specs by status code to support multiple present responses
+      def group_specs_by_status(specs)
+        specs.group_by { |s| s[:code].to_s }
+      end
+
+      # Builds a response from a group of specs with the same status code
+      # If multiple specs have `as:` keys, they are merged into a single object schema
+      def build_response_from_group(group_specs)
+        if group_specs.any? { |s| s[:as] }
+          build_merged_response(group_specs)
+        else
+          build_response_from_spec(group_specs.first)
+        end
+      end
+
+      # Builds a merged response for multiple present with `as:` keys
+      def build_merged_response(specs)
+        first_spec = specs.first
+        schema = build_merged_schema(specs)
+        media_types = Array(response_content_types).map do |mime|
+          build_media_type(mime_type: mime, schema: schema)
+        end
+
+        description = first_spec[:message].is_a?(String) ? first_spec[:message] : first_spec[:message].to_s
+
+        GrapeOAS::ApiModel::Response.new(
+          http_status: first_spec[:code].to_s,
+          description: description || "Success",
+          media_types: media_types,
+          headers: normalize_headers(first_spec[:headers]) || headers_from_route,
+          extensions: first_spec[:extensions] || extensions_from_route,
+          examples: merge_examples(specs),
+        )
+      end
+
+      # Builds an object schema with properties from each `as:` keyed spec
+      def build_merged_schema(specs)
+        properties = {}
+        required = []
+
+        specs.each do |spec|
+          key = spec[:as].to_s
+          entity_schema = build_schema(spec[:entity])
+
+          properties[key] = if spec[:is_array]
+                              GrapeOAS::ApiModel::Schema.new(
+                                type: Constants::SchemaTypes::ARRAY,
+                                items: entity_schema,
+                              )
+                            else
+                              entity_schema
+                            end
+
+          required << key if spec[:required]
+        end
+
+        GrapeOAS::ApiModel::Schema.new(
+          type: Constants::SchemaTypes::OBJECT,
+          properties: properties,
+          required: required.empty? ? nil : required,
+        )
+      end
+
+      # Merges examples from multiple specs
+      def merge_examples(specs)
+        examples = specs.map { |s| s[:examples] }.compact
+        return nil if examples.empty?
+
+        examples.reduce({}, :merge)
+      end
+
+      def build_response_from_spec(spec)
+        entity_schema = build_schema(spec[:entity])
+        schema = wrap_with_root(entity_schema, spec[:entity], is_array: spec[:is_array])
+        media_types = Array(response_content_types).map do |mime|
+          build_media_type(
+            mime_type: mime,
+            schema: schema,
+          )
+        end
+
+        description = spec[:message].is_a?(String) ? spec[:message] : spec[:message].to_s
+
+        GrapeOAS::ApiModel::Response.new(
+          http_status: spec[:code].to_s,
+          description: description || "Success",
+          media_types: media_types,
+          headers: normalize_headers(spec[:headers]) || headers_from_route,
+          extensions: spec[:extensions] || extensions_from_route,
+          examples: spec[:examples],
+        )
+      end
+
+      def extensions_from_route
+        extract_extensions(route.options[:documentation])
+      end
+
+      def normalize_headers(hdrs)
+        return nil if hdrs.nil?
+        return hdrs if hdrs.is_a?(Array)
+        return nil unless hdrs.is_a?(Hash)
+
+        hdrs.map { |name, h| build_header_schema(name, h) }
+      end
+
+      def headers_from_route
+        hdrs = route.options.dig(:documentation, :headers) || route.settings.dig(:documentation, :headers)
+        return [] unless hdrs.is_a?(Hash)
+
+        hdrs.map { |name, h| build_header_schema(name, h) }
+      end
+
+      # Build a header schema, normalizing field names
+      def build_header_schema(name, header_spec)
+        {
+          name: name,
+          schema: {
+            "type" => header_spec[:type] || header_spec["type"] || Constants::SchemaTypes::STRING,
+            "description" => header_spec[:description] || header_spec["description"] || header_spec[:desc]
+          }.compact
+        }
+      end
+
+      # Build schema for response body
+      # Delegates to EntityIntrospector when entity is present
+      def build_schema(entity_class)
+        return GrapeOAS::ApiModel::Schema.new(type: Constants::SchemaTypes::STRING) unless entity_class
+
+        GrapeOAS::Introspectors::EntityIntrospector.new(entity_class).build_schema
+      end
+
+      # Wraps schema with root element if configured via route_setting :swagger, root: true/'name'
+      def wrap_with_root(schema, entity_class, is_array: false)
+        root_setting = route.settings.dig(:swagger, :root)
+        return schema unless root_setting
+
+        root_key = derive_root_key(root_setting, entity_class, is_array)
+        GrapeOAS::ApiModel::Schema.new(
+          type: Constants::SchemaTypes::OBJECT,
+          properties: { root_key => schema },
+        )
+      end
+
+      # Derives the root key name based on the setting
+      def derive_root_key(root_setting, entity_class, is_array)
+        case root_setting
+        when true
+          key = entity_name_to_key(entity_class)
+          is_array ? pluralize_key(key) : key
+        when String, Symbol
+          root_setting.to_s
+        else
+          entity_name_to_key(entity_class)
+        end
+      end
+
+      # Converts entity class name to underscored key
+      def entity_name_to_key(entity_class)
+        return "data" unless entity_class
+
+        name = entity_class.is_a?(Class) ? entity_class.name : entity_class.to_s
+        # Remove common suffixes like Entity, Serializer
+        name = name.split("::").last || name
+        name = name.sub(/Entity$/, "").sub(/Serializer$/, "")
+        underscore(name)
+      end
+
+      def pluralize_key(key)
+        pluralize(key)
+      end
+
+      def build_media_type(mime_type:, schema:)
+        GrapeOAS::ApiModel::MediaType.new(
+          mime_type: mime_type,
+          schema: schema,
+        )
+      end
+
+      def response_content_types
+        resolve_content_types
+      end
+    end
+  end
+end

data/lib/grape_oas/api_model_builders/response_parsers/base.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module ApiModelBuilders
+    module ResponseParsers
+      # Base module for response parser strategies
+      # Each parser is responsible for extracting response specifications
+      # from a specific format (e.g., :http_codes, documentation: { responses: ... })
+      module Base
+        # Parse response specifications from the route
+        # @param route [Grape::Route] The route to parse
+        # @return [Array<Hash>] Array of normalized response specs with keys:
+        #   - code: HTTP status code
+        #   - message: Response description
+        #   - entity: Entity class for response schema
+        #   - headers: Response headers
+        #   - extensions: Custom x- extensions (optional)
+        #   - examples: Response examples (optional)
+        def parse(route)
+          raise NotImplementedError, "#{self.class} must implement #parse"
+        end
+
+        # Check if this parser can handle the given route
+        # @param route [Grape::Route] The route to check
+        # @return [Boolean] true if this parser can parse the route
+        def applicable?(route)
+          raise NotImplementedError, "#{self.class} must implement #applicable?"
+        end
+
+        private
+
+        # Extract status code from hash, supporting multiple key names
+        def extract_status_code(hash, default_code)
+          hash[:code] || hash[:status] || hash[:http_status] || default_code
+        end
+
+        # Extract description from hash, supporting multiple key names
+        def extract_description(hash)
+          hash[:message] || hash[:description] || hash[:desc]
+        end
+
+        # Extract entity from hash, supporting multiple key names
+        def extract_entity(hash, fallback_entity)
+          hash[:model] || hash[:entity] || fallback_entity
+        end
+
+        # Normalize hash keys (string -> symbol)
+        def normalize_hash_keys(hash)
+          return hash unless hash.is_a?(Hash)
+
+          hash.transform_keys { |k| k.is_a?(String) ? k.to_sym : k }
+        end
+      end
+    end
+  end
+end

data/lib/grape_oas/api_model_builders/response_parsers/default_response_parser.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module ApiModelBuilders
+    module ResponseParsers
+      # Parser that creates a default 200 response when no responses are defined
+      # This is the fallback parser used when no other parsers are applicable
+      class DefaultResponseParser
+        include Base
+
+        def applicable?(_route)
+          # Always applicable as a fallback
+          true
+        end
+
+        def parse(route)
+          inferred = route.options[:default_status]
+          inferred ||= route.request_method.to_s.upcase == "POST" ? 201 : 200
+          default_code = inferred.to_s
+
+          [{
+            code: default_code,
+            message: "Success",
+            entity: route.options[:entity],
+            headers: nil
+          }]
+        end
+      end
+    end
+  end
+end

data/lib/grape_oas/api_model_builders/response_parsers/documentation_responses_parser.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module ApiModelBuilders
+    module ResponseParsers
+      # Parser for responses defined in documentation: { responses: { ... } }
+      # This is the most comprehensive format and aligns with OpenAPI specification
+      class DocumentationResponsesParser
+        include Base
+        include Concerns::OasUtilities
+
+        def applicable?(route)
+          route.options.dig(:documentation, :responses).is_a?(Hash)
+        end
+
+        def parse(route)
+          doc_resps = route.options.dig(:documentation, :responses)
+          return [] unless doc_resps.is_a?(Hash)
+
+          doc_resps.map do |code, doc|
+            doc = normalize_hash_keys(doc)
+            {
+              code: code,
+              message: extract_description(doc),
+              headers: doc[:headers],
+              entity: extract_entity(doc, route.options[:entity]),
+              extensions: extract_extensions(doc),
+              examples: doc[:examples]
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/grape_oas/api_model_builders/response_parsers/http_codes_parser.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module ApiModelBuilders
+    module ResponseParsers
+      # Parser for responses defined via :http_codes, :failure, or :success options
+      # These are legacy grape-swagger formats that we support for compatibility
+      class HttpCodesParser
+        include Base
+
+        def applicable?(route)
+          route.options[:http_codes] || route.options[:failure] || route.options[:success]
+        end
+
+        def parse(route)
+          specs = []
+
+          specs.concat(parse_option(route, :http_codes)) if route.options[:http_codes]
+          specs.concat(parse_option(route, :failure)) if route.options[:failure]
+          specs.concat(parse_option(route, :success)) if route.options[:success]
+
+          specs
+        end
+
+        private
+
+        def parse_option(route, option_key)
+          value = route.options[option_key]
+          return [] unless value
+
+          items = value.is_a?(Hash) ? [value] : Array(value)
+          items.map { |entry| normalize_entry(entry, route) }
+        end
+
+        def normalize_entry(entry, route)
+          case entry
+          when Hash
+            normalize_hash_entry(entry, route)
+          when Array
+            normalize_array_entry(entry, route)
+          else
+            normalize_plain_entry(entry, route)
+          end
+        end
+
+        def normalize_hash_entry(entry, route)
+          default_code = (route.options[:default_status] || 200).to_s
+          {
+            code: extract_status_code(entry, default_code),
+            message: extract_description(entry),
+            entity: extract_entity(entry, route.options[:entity]),
+            headers: entry[:headers],
+            examples: entry[:examples],
+            as: entry[:as],
+            is_array: entry[:is_array] || route.options[:is_array],
+            required: entry[:required]
+          }
+        end
+
+        def normalize_array_entry(entry, route)
+          return normalize_plain_entry(nil, route) if entry.empty?
+
+          code, message, entity, examples = entry
+          {
+            code: code,
+            message: message,
+            entity: entity || route.options[:entity],
+            headers: nil,
+            examples: examples
+          }
+        end
+
+        def normalize_plain_entry(entry, route)
+          # Plain status code (e.g., 404)
+          {
+            code: entry,
+            message: nil,
+            entity: route.options[:entity],
+            headers: nil
+          }
+        end
+      end
+    end
+  end
+end

data/lib/grape_oas/constants.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  # Central location for constants used throughout the gem
+  module Constants
+    # OpenAPI/JSON Schema type strings
+    module SchemaTypes
+      STRING = "string"
+      INTEGER = "integer"
+      NUMBER = "number"
+      BOOLEAN = "boolean"
+      OBJECT = "object"
+      ARRAY = "array"
+      FILE = "file"
+
+      ALL = [STRING, INTEGER, NUMBER, BOOLEAN, OBJECT, ARRAY, FILE].freeze
+    end
+
+    # Common MIME types
+    module MimeTypes
+      JSON = "application/json"
+      XML = "application/xml"
+      FORM_URLENCODED = "application/x-www-form-urlencoded"
+      MULTIPART_FORM = "multipart/form-data"
+
+      ALL = [JSON, XML, FORM_URLENCODED, MULTIPART_FORM].freeze
+    end
+
+    # Default values for OpenAPI spec when not provided by user
+    module Defaults
+      LICENSE_NAME = "Proprietary"
+      LICENSE_URL = "https://example.com/license"
+      LICENSE_IDENTIFIER = "UNLICENSED"
+      SERVER_URL = "https://api.example.com"
+    end
+
+    # Ruby class to schema type mapping.
+    # Used for automatic type inference from parameter declarations.
+    # Note: String is not included as it's the default fallback.
+    RUBY_TYPE_MAPPING = {
+      Integer => SchemaTypes::INTEGER,
+      Float => SchemaTypes::NUMBER,
+      BigDecimal => SchemaTypes::NUMBER,
+      TrueClass => SchemaTypes::BOOLEAN,
+      FalseClass => SchemaTypes::BOOLEAN,
+      Array => SchemaTypes::ARRAY,
+      Hash => SchemaTypes::OBJECT,
+      File => SchemaTypes::FILE
+    }.freeze
+
+    # String type name to schema type mapping (lowercase).
+    # Supports lookup with any case via primitive_type helper.
+    # Note: float and bigdecimal both map to NUMBER as they represent
+    # the same OpenAPI numeric type.
+    PRIMITIVE_TYPE_MAPPING = {
+      "float" => SchemaTypes::NUMBER,
+      "bigdecimal" => SchemaTypes::NUMBER,
+      "string" => SchemaTypes::STRING,
+      "integer" => SchemaTypes::INTEGER,
+      "number" => SchemaTypes::NUMBER,
+      "boolean" => SchemaTypes::BOOLEAN,
+      "grape::api::boolean" => SchemaTypes::BOOLEAN,
+      "trueclass" => SchemaTypes::BOOLEAN,
+      "falseclass" => SchemaTypes::BOOLEAN,
+      "array" => SchemaTypes::ARRAY,
+      "hash" => SchemaTypes::OBJECT,
+      "object" => SchemaTypes::OBJECT,
+      "file" => SchemaTypes::FILE,
+      "rack::multipart::uploadedfile" => SchemaTypes::FILE
+    }.freeze
+
+    # Resolves a primitive type name to its OpenAPI schema type.
+    # Normalizes the key to lowercase for consistent lookup.
+    #
+    # @param key [String, Symbol] The type name to resolve
+    # @return [String, nil] The OpenAPI schema type or nil if not found
+    def self.primitive_type(key)
+      PRIMITIVE_TYPE_MAPPING[key.to_s.downcase]
+    end
+  end
+end

data/lib/grape_oas/documentation_extension.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module GrapeOAS
+  module DocumentationExtension
+    # Primary entry for grape-oas documentation
+    def add_oas_documentation(**options)
+      return if options.delete(:hide_documentation_path)
+
+      # Prefer grape-oas namespaced options to avoid clashing with grape-swagger
+      default_mount_path = options.delete(:oas_mount_path) ||
+                           options.delete(:mount_path) ||
+                           "/swagger_doc"
+      default_format = options.delete(:oas_doc_version) ||
+                       options.delete(:doc_version) ||
+                       :oas3
+      cache_control = options.delete(:cache_control)
+      etag_value = options.delete(:etag)
+
+      mount_paths = {
+        default: default_mount_path,
+        oas2: options.delete(:oas_mount_path_v2) || options.delete(:mount_path_v2),
+        oas3: options.delete(:oas_mount_path_v3) || options.delete(:mount_path_v3)
+      }.compact
+
+      api = self
+
+      mount_paths.each do |key, path|
+        add_documentation_routes(path, key, default_format, cache_control, etag_value, options, api)
+      end
+    end
+
+    def add_documentation_routes(path, key, default_format, cache_control, etag_value, options, api)
+      # Main route without namespace filter
+      add_route(path) do
+        GrapeOAS::DocumentationExtension.generate_documentation(
+          self, api, key, default_format, cache_control, etag_value, options, nil,
+        )
+      end
+
+      # Route with namespace filter: /swagger_doc/:namespace
+      # Supports nested namespaces via *namespace (catches slashes)
+      add_route("#{path}/*namespace") do
+        namespace_filter = params[:namespace]&.sub(/\.json$/, "")
+        GrapeOAS::DocumentationExtension.generate_documentation(
+          self, api, key, default_format, cache_control, etag_value, options, namespace_filter,
+        )
+      end
+    end
+
+    def self.generate_documentation(endpoint, api, key, default_format, cache_control, etag_value, options, namespace_filter)
+      schema_type = if key == :oas2
+                      :oas2
+                    elsif key == :oas3
+                      :oas3
+                    else
+                      parse_schema_type(endpoint.params[:oas]) || default_format
+                    end
+
+      endpoint.header("Cache-Control", cache_control) if cache_control
+      endpoint.header("ETag", etag_value) if etag_value
+
+      # Resolve runtime options (like grape-swagger's OptionalObject)
+      runtime_options = options.dup
+      runtime_options[:host] = resolve_option(
+        runtime_options[:host], endpoint.request, :host_with_port,
+      )
+      runtime_options[:base_path] = resolve_option(
+        runtime_options[:base_path], endpoint.request, :script_name,
+      )
+      runtime_options[:namespace] = namespace_filter if namespace_filter
+
+      GrapeOAS.generate(app: api, schema_type: schema_type, **runtime_options)
+    end
+
+    # Compatibility shim for apps calling grape-swagger's add_swagger_documentation.
+    #
+    # If grape-swagger is loaded we defer to its implementation to keep legacy
+    # behaviour untouched. Only when grape-swagger is absent do we fall back to
+    # grape-oas.
+    def add_swagger_documentation(**options)
+      return super if defined?(::GrapeSwagger)
+
+      options = options.dup
+      options[:oas_doc_version] ||= :oas2
+      options[:oas_mount_path] ||= options[:mount_path] || "/swagger_doc.json"
+      add_oas_documentation(**options)
+    end
+
+    private
+
+    # Minimal route mounting helper
+    def add_route(path, &block)
+      api_class = self
+      namespace do
+        get(path) { instance_exec(api_class, &block) }
+      end
+    end
+
+    def parse_schema_type(value)
+      case value&.to_s
+      when "2", "oas2", "swagger"
+        :oas2
+      when "3.1", "31", "oas31", "oas3_1", "openapi31"
+        :oas31
+      when "3", "oas3", "openapi", "oas30", "oas3_0", "openapi30"
+        :oas3
+      end
+    end
+    module_function :parse_schema_type
+
+    # Resolve option value at request time (like grape-swagger's OptionalObject)
+    # Supports: static values, Proc/lambda (with optional request arg), or fallback to request method
+    def resolve_option(value, request, default_method)
+      if value.is_a?(Proc)
+        value.arity.zero? ? value.call : value.call(request)
+      elsif value
+        value
+      elsif request
+        request.send(default_method)
+      end
+    end
+    module_function :resolve_option
+  end
+end