rspec-openapi 0.1.0 → 0.18.4

data/lib/rspec/openapi/schema_builder.rb

@@ -1,23 +1,44 @@
+# frozen_string_literal: true
+
 class << RSpec::OpenAPI::SchemaBuilder = Object.new
   # @param [RSpec::OpenAPI::Record] record
   # @return [Hash]
   def build(record)
+    response = {
+      description: record.description,
+    }
+
+    response_headers = build_response_headers(record)
+    response[:headers] = response_headers unless response_headers.empty?
+
+    if record.response_body
+      disposition = normalize_content_disposition(record.response_content_disposition)
+
+      has_content = !normalize_content_type(record.response_content_type).nil?
+      if has_content
+        response[:content] = {
+          normalize_content_type(record.response_content_type) => {
+            schema: build_property(record.response_body, disposition: disposition),
+            example: response_example(record, disposition: disposition),
+          }.compact,
+        }
+      end
+    end
+
+    http_method = record.http_method.downcase
     {
       paths: {
-        record.path => {
-          record.method.downcase => {
-            summary: "#{record.controller}##{record.action}",
+        normalize_path(record.path) => {
+          http_method => {
+            summary: record.summary,
+            tags: record.tags,
+            operationId: record.operation_id,
+            security: record.security,
+            deprecated: record.deprecated ? true : nil,
             parameters: build_parameters(record),
-            requestBody: build_request_body(record),
+            requestBody: include_nil_request_body?(http_method) ? nil : build_request_body(record),
             responses: {
-              record.status.to_s => {
-                description: record.description,
-                content: {
-                  normalize_content_type(record.response_content_type) => {
-                    schema: build_property(record.response_body),
-                  },
-                },
-              },
+              record.status.to_s => response,
             },
           }.compact,
         },
@@ -27,72 +48,140 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
 
   private
 
-  def build_parameters(record)
-    parameters = []
+  def include_nil_request_body?(http_method)
+    %w[delete get].include?(http_method)
+  end
 
-    record.path_params.each do |key, value|
-      next if %i[controller action].include?(key)
-      parameters << {
-        name: key.to_s,
+  def enrich_with_required_keys(obj)
+    obj[:required] = obj[:properties]&.keys || []
+    obj
+  end
+
+  def response_example(record, disposition:)
+    return nil if !example_enabled? || disposition
+
+    record.response_body
+  end
+
+  def example_enabled?
+    RSpec::OpenAPI.enable_example
+  end
+
+  def build_parameters(record)
+    path_params = record.path_params.map do |key, value|
+      {
+        name: build_parameter_name(key, value),
         in: 'path',
+        required: true,
         schema: build_property(try_cast(value)),
-      }
+        example: (try_cast(value) if example_enabled?),
+      }.compact
     end
 
-    record.query_params.each do |key, value|
-      parameters << {
-        name: key.to_s,
+    query_params = record.query_params.map do |key, value|
+      {
+        name: build_parameter_name(key, value),
         in: 'query',
+        required: record.required_request_params.include?(key),
+        schema: build_property(try_cast(value)),
+        example: (try_cast(value) if example_enabled?),
+      }.compact
+    end
+
+    header_params = record.request_headers.map do |key, value|
+      {
+        name: build_parameter_name(key, value),
+        in: 'header',
+        required: true,
         schema: build_property(try_cast(value)),
-      }
+        example: (try_cast(value) if example_enabled?),
+      }.compact
     end
 
+    parameters = path_params + query_params + header_params
+
     return nil if parameters.empty?
+
     parameters
   end
 
+  def build_response_headers(record)
+    headers = {}
+
+    record.response_headers.each do |key, value|
+      headers[key] = {
+        schema: build_property(try_cast(value)),
+      }.compact
+    end
+
+    headers
+  end
+
+  def build_parameter_name(key, value)
+    key = key.to_s
+    if value.is_a?(Hash) && (value_keys = value.keys).size == 1
+      value_key = value_keys.first
+      build_parameter_name("#{key}[#{value_key}]", value[value_key])
+    else
+      key
+    end
+  end
+
   def build_request_body(record)
     return nil if record.request_content_type.nil?
-    return nil if record.request_params.empty?
+    return nil if record.status >= 400
 
     {
       content: {
         normalize_content_type(record.request_content_type) => {
           schema: build_property(record.request_params),
-        }
-      }
+          example: (build_example(record.request_params) if example_enabled?),
+        }.compact,
+      },
     }
   end
 
-  def build_property(value)
-    property = { type: build_type(value) }
+  def build_property(value, disposition: nil)
+    property = build_type(value, disposition)
+
     case value
     when Array
-      property[:items] = build_property(value.first)
+      property[:items] = if value.empty?
+                           {} # unknown
+                         else
+                           build_property(value.first)
+                         end
     when Hash
       property[:properties] = {}.tap do |properties|
         value.each do |key, v|
           properties[key] = build_property(v)
         end
       end
+      property = enrich_with_required_keys(property)
     end
     property
   end
 
-  def build_type(value)
+  def build_type(value, disposition)
+    return { type: 'string', format: 'binary' } if disposition
+
     case value
     when String
-      'string'
+      { type: 'string' }
     when Integer
-      'integer'
+      { type: 'integer' }
+    when Float
+      { type: 'number', format: 'float' }
     when TrueClass, FalseClass
-      'boolean'
+      { type: 'boolean' }
     when Array
-      'array'
+      { type: 'array' }
     when Hash
-      'object'
+      { type: 'object' }
+    when ActionDispatch::Http::UploadedFile
+      { type: 'string', format: 'binary' }
     when NilClass
-      'null'
+      { nullable: true }
     else
       raise NotImplementedError, "type detection is not implemented for: #{value.inspect}"
     end
@@ -100,14 +189,50 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
 
   # Convert an always-String param to an appropriate type
   def try_cast(value)
-    begin
-      Integer(value)
-    rescue TypeError, ArgumentError
-      value
+    Integer(value)
+  rescue TypeError, ArgumentError
+    value
+  end
+
+  def build_example(value)
+    return nil if value.nil?
+
+    value = value.dup
+    adjust_params(value)
+  end
+
+  def adjust_params(value)
+    value.each do |key, v|
+      case v
+      when ActionDispatch::Http::UploadedFile
+        value[key] = v.original_filename
+      when Hash
+        adjust_params(v)
+      when Array
+        result = v.map do |item|
+          case item
+          when ActionDispatch::Http::UploadedFile
+            item.original_filename
+          when Hash
+            adjust_params(item)
+          else
+            item
+          end
+        end
+        value[key] = result
+      end
     end
   end
 
+  def normalize_path(path)
+    path.gsub(%r{/:([^:/]+)}, '/{\1}')
+  end
+
   def normalize_content_type(content_type)
-    content_type.sub(/;.+\z/, '')
+    content_type&.sub(/;.+\z/, '')
+  end
+
+  def normalize_content_disposition(content_disposition)
+    content_disposition&.sub(/;.+\z/, '')
   end
 end

data/lib/rspec/openapi/schema_cleaner.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+# For Ruby 3.0+
+require 'set'
+
+require_relative 'hash_helper'
+
+class << RSpec::OpenAPI::SchemaCleaner = Object.new
+  # Cleanup the properties, of component schemas, that exists in the base but not in the spec.
+  #
+  # @param [Hash] base
+  # @param [Hash] spec
+  def cleanup_components_schemas!(base, spec)
+    cleanup_hash!(base, spec, 'components.schemas.*')
+    cleanup_hash!(base, spec, 'components.schemas.*.properties.*')
+  end
+
+  # Cleanup specific elements that exists in the base but not in the spec
+  #
+  # @param [Hash] base
+  # @param [Hash] spec
+  def cleanup!(base, spec)
+    # cleanup URLs
+    cleanup_hash!(base, spec, 'paths.*')
+
+    # cleanup HTTP methods
+    cleanup_hash!(base, spec, 'paths.*.*')
+
+    # cleanup parameters
+    cleanup_array!(base, spec, 'paths.*.*.parameters', %i[name in])
+
+    # cleanup requestBody
+    cleanup_hash!(base, spec, 'paths.*.*.requestBody.content.application/json.schema.properties.*')
+    cleanup_hash!(base, spec, 'paths.*.*.requestBody.content.application/json.example.*')
+
+    # cleanup responses
+    cleanup_hash!(base, spec, 'paths.*.*.responses.*.content.application/json.schema.properties.*')
+    cleanup_hash!(base, spec, 'paths.*.*.responses.*.content.application/json.example.*')
+    base
+  end
+
+  def cleanup_conflicting_security_parameters!(base)
+    security_schemes = base.dig(:components, :securitySchemes) || {}
+
+    return if security_schemes.empty?
+
+    paths_to_security_definitions = RSpec::OpenAPI::HashHelper.matched_paths_deeply_nested(base, 'paths', 'security')
+
+    paths_to_security_definitions.each do |path|
+      parent_path_definition = base.dig(*path.take(path.length - 1))
+
+      security_schemes.each do |security_scheme_name, security_scheme|
+        remove_parameters_conflicting_with_security_sceheme!(
+          parent_path_definition, security_scheme, security_scheme_name,
+        )
+      end
+    end
+  end
+
+  def cleanup_empty_required_array!(base)
+    paths_to_objects = [
+      *RSpec::OpenAPI::HashHelper.matched_paths_deeply_nested(base, 'components.schemas', 'properties'),
+      *RSpec::OpenAPI::HashHelper.matched_paths_deeply_nested(base, 'paths', 'properties'),
+    ]
+    paths_to_objects.each do |path|
+      parent = base.dig(*path.take(path.length - 1))
+      # "required" array  must not be present if empty
+      parent.delete(:required) if parent[:required] && parent[:required].empty?
+    end
+  end
+
+  private
+
+  def remove_parameters_conflicting_with_security_sceheme!(path_definition, security_scheme, security_scheme_name)
+    return unless path_definition[:security]
+    return unless path_definition[:parameters]
+    return unless path_definition.dig(:security, 0).keys.include?(security_scheme_name)
+
+    path_definition[:parameters].reject! do |parameter|
+      parameter[:in] == security_scheme[:in] && # same location (ie. header)
+        parameter[:name] == security_scheme[:name] # same name (ie. AUTHORIZATION)
+    end
+    path_definition.delete(:parameters) if path_definition[:parameters].empty?
+  end
+
+  def cleanup_array!(base, spec, selector, fields_for_identity = [])
+    marshal = lambda do |obj|
+      Marshal.dump(slice(obj, fields_for_identity))
+    end
+
+    RSpec::OpenAPI::HashHelper.matched_paths(base, selector).each do |paths|
+      target_array = base.dig(*paths)
+      spec_array = spec.dig(*paths)
+      next unless target_array.is_a?(Array) && spec_array.is_a?(Array)
+
+      spec_identities = Set.new(spec_array.map(&marshal))
+      target_array.select! { |e| spec_identities.include?(marshal.call(e)) }
+      target_array.sort_by! { |param| fields_for_identity.map { |f| param[f] }.join('-') }
+      # Keep the last duplicate to produce the result stably
+      deduplicated = target_array.reverse.uniq { |param| slice(param, fields_for_identity) }.reverse
+      target_array.replace(deduplicated)
+    end
+    base
+  end
+
+  def cleanup_hash!(base, spec, selector)
+    RSpec::OpenAPI::HashHelper.matched_paths(base, selector).each do |paths|
+      exist_in_base = !base.dig(*paths).nil?
+      not_in_spec = spec.dig(*paths).nil?
+      if exist_in_base && not_in_spec
+        if paths.size == 1
+          base.delete(paths.last)
+        else
+          parent_node = base.dig(*paths[0..-2])
+          parent_node.delete(paths.last)
+        end
+      end
+    end
+    base
+  end
+
+  def slice(obj, fields_for_identity)
+    if fields_for_identity.any?
+      obj.slice(*fields_for_identity)
+    else
+      obj
+    end
+  end
+end

data/lib/rspec/openapi/schema_file.rb

@@ -1,5 +1,8 @@
+# frozen_string_literal: true
+
 require 'fileutils'
 require 'yaml'
+require 'json'
 
 # TODO: Support JSON
 class RSpec::OpenAPI::SchemaFile
@@ -12,7 +15,7 @@ class RSpec::OpenAPI::SchemaFile
     spec = read
     block.call(spec)
   ensure
-    write(spec)
+    write(RSpec::OpenAPI::KeyTransformer.stringify(spec))
   end
 
   private
@@ -20,12 +23,31 @@ class RSpec::OpenAPI::SchemaFile
   # @return [Hash]
   def read
     return {} unless File.exist?(@path)
-    YAML.load(File.read(@path))
+
+    RSpec::OpenAPI::KeyTransformer.symbolize(YAML.safe_load(File.read(@path))) # this can also parse JSON
   end
 
   # @param [Hash] spec
   def write(spec)
     FileUtils.mkdir_p(File.dirname(@path))
-    File.write(@path, YAML.dump(spec))
+    output =
+      if json?
+        JSON.pretty_generate(spec)
+      else
+        prepend_comment(YAML.dump(spec))
+      end
+    File.write(@path, output)
+  end
+
+  def prepend_comment(content)
+    return content if RSpec::OpenAPI.comment.nil?
+
+    comment = RSpec::OpenAPI.comment.dup
+    comment << "\n" unless comment.end_with?("\n")
+    "#{comment.gsub(/^/, '# ').gsub(/^# \n/, "#\n")}#{content}"
+  end
+
+  def json?
+    File.extname(@path) == '.json'
   end
 end

data/lib/rspec/openapi/schema_merger.rb

@@ -1,37 +1,107 @@
+# frozen_string_literal: true
+
 class << RSpec::OpenAPI::SchemaMerger = Object.new
   # @param [Hash] base
   # @param [Hash] spec
-  def reverse_merge!(base, spec)
-    spec = normalize_keys(spec)
-    deep_reverse_merge!(base, spec)
+  def merge!(base, spec)
+    spec = RSpec::OpenAPI::KeyTransformer.symbolize(spec)
+    base.replace(RSpec::OpenAPI::KeyTransformer.symbolize(base))
+    merge_schema!(base, spec)
   end
 
   private
 
-  def normalize_keys(spec)
-    case spec
-    when Hash
-      spec.map do |key, value|
-        [key.to_s, normalize_keys(value)]
-      end.to_h
-    when Array
-      spec.map { |s| normalize_keys(s) }
-    else
-      spec
+  # Not doing `base.replace(deep_merge(base, spec))` to preserve key orders.
+  # Also this needs to be aware of OpenAPI details because a Hash-like structure
+  # may be an array whose Hash elements have a key name.
+  #
+  # TODO: Should we probably force-merge `summary` regardless of manual modifications?
+  def merge_schema!(base, spec)
+    if (options = base[:oneOf])
+      merge_closest_match!(options, spec)
+
+      return base
     end
-  end
 
-  # Not doing `base.replace(deep_merge(base, spec))` to preserve key orders
-  # TODO: Perform more intelligent merges like rerouting edits / merging types
-  # Should we probably force-merge `summary` regardless of manual modifications?
-  def deep_reverse_merge!(base, spec)
     spec.each do |key, value|
       if base[key].is_a?(Hash) && value.is_a?(Hash)
-        deep_reverse_merge!(base[key], value)
-      elsif !base.key?(key)
-        base[key] = value
+        merge_schema!(base[key], value) unless base[key].key?(:$ref)
+      elsif base[key].is_a?(Array) && value.is_a?(Array)
+        # parameters need to be merged as if `name` and `in` were the Hash keys.
+        merge_arrays(base, key, value)
+      else
+        # do not ADD `properties` or `required` fields if `additionalProperties` field is present
+        base[key] = value unless base.key?(:additionalProperties) && %i[properties required].include?(key)
       end
     end
     base
   end
+
+  def merge_arrays(base, key, value)
+    base[key] = case key
+                when :parameters
+                  merge_parameters(base, key, value)
+                when :required
+                  # Preserve properties that appears in all test cases
+                  value & base[key]
+                else
+                  # last one wins
+                  value
+                end
+  end
+
+  def merge_parameters(base, key, value)
+    all_parameters = value | base[key]
+
+    unique_base_parameters = build_unique_params(base, key)
+
+    all_parameters = all_parameters.map do |parameter|
+      base_parameter = unique_base_parameters[[parameter[:name], parameter[:in]]] || {}
+      base_parameter ? base_parameter.merge(parameter) : parameter
+    end
+
+    all_parameters.uniq! { |param| param.slice(:name, :in) }
+    base[key] = all_parameters
+  end
+
+  def build_unique_params(base, key)
+    base[key].each_with_object({}) do |parameter, hash|
+      hash[[parameter[:name], parameter[:in]]] = parameter
+    end
+  end
+
+  SIMILARITY_THRESHOLD = 0.5
+
+  def merge_closest_match!(options, spec)
+    score, option = options.map { |option| [similarity(option, spec), option] }.max_by(&:first)
+
+    return if option&.key?(:$ref)
+
+    if score.to_f > SIMILARITY_THRESHOLD
+      merge_schema!(option, spec)
+    else
+      options.push(spec)
+    end
+  end
+
+  def similarity(first, second)
+    return 1 if first == second
+
+    score =
+      case [first.class, second.class]
+      when [Array, Array]
+        (first & second).size / [first.size, second.size].max.to_f
+      when [Hash, Hash]
+        return 1 if first.merge(second).key?(:$ref)
+
+        intersection = first.keys & second.keys
+        total_size = [first.size, second.size].max.to_f
+
+        intersection.sum { |key| similarity(first[key], second[key]) } / total_size
+      else
+        0
+      end
+
+    score.finite? ? score : 0
+  end
 end

data/lib/rspec/openapi/schema_sorter.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+class << RSpec::OpenAPI::SchemaSorter = Object.new
+  # Sort some unpredictably ordered properties in a lexicographical manner to make the order more predictable.
+  #
+  # @param [Hash|Array]
+  def deep_sort!(spec)
+    # paths
+    deep_sort_by_selector!(spec, 'paths')
+
+    # methods
+    deep_sort_by_selector!(spec, 'paths.*')
+
+    # response status code
+    deep_sort_by_selector!(spec, 'paths.*.*.responses')
+
+    # content-type
+    deep_sort_by_selector!(spec, 'paths.*.*.responses.*.content')
+  end
+
+  private
+
+  # @param [Hash] base
+  # @param [String] selector
+  def deep_sort_by_selector!(base, selector)
+    RSpec::OpenAPI::HashHelper.matched_paths(base, selector).each do |paths|
+      deep_sort_hash!(base.dig(*paths))
+    end
+  end
+
+  def deep_sort_hash!(hash)
+    sorted = hash.entries.sort_by { |k, _| k.to_s }.to_h.transform_keys(&:to_sym)
+    hash.replace(sorted)
+  end
+end

data/lib/rspec/openapi/shared_hooks.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module SharedHooks
+  def self.find_extractor
+    if defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+      RSpec::OpenAPI::Extractors::Rails
+    elsif defined?(Hanami) && Hanami.respond_to?(:app) && Hanami.app?
+      RSpec::OpenAPI::Extractors::Hanami
+      # elsif defined?(Roda)
+      #   some Roda extractor
+    else
+      RSpec::OpenAPI::Extractors::Rack
+    end
+  end
+end

data/lib/rspec/openapi/version.rb

@@ -1,5 +1,7 @@
+# frozen_string_literal: true
+
 module RSpec
   module OpenAPI
-    VERSION = '0.1.0'
+    VERSION = '0.18.4'
   end
 end