rspec-openapi 0.1.0 → 0.18.4

data/lib/rspec/openapi/extractors/rails.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+# Extractor for rails
+class << RSpec::OpenAPI::Extractors::Rails = Object.new
+  # @param [ActionDispatch::Request] request
+  # @param [RSpec::Core::Example] example
+  # @return Array
+  def request_attributes(request, example)
+    # Reverse the destructive modification by Rails https://github.com/rails/rails/blob/v6.0.3.4/actionpack/lib/action_dispatch/journey/router.rb#L33-L41
+    fixed_request = request.dup
+    fixed_request.path_info = File.join(request.script_name, request.path_info) if request.script_name.present?
+
+    route, path = find_rails_route(fixed_request)
+
+    return RSpec::OpenAPI::Extractors::Rack.request_attributes(request, example) unless path
+
+    raise "No route matched for #{fixed_request.request_method} #{fixed_request.path_info}" if route.nil?
+
+    metadata = example.metadata[:openapi] || {}
+    summary = metadata[:summary] || RSpec::OpenAPI.summary_builder.call(example)
+    tags = metadata[:tags] || RSpec::OpenAPI.tags_builder.call(example)
+    operation_id = metadata[:operation_id]
+    required_request_params = metadata[:required_request_params] || []
+    security = metadata[:security]
+    description = metadata[:description] || RSpec::OpenAPI.description_builder.call(example)
+    deprecated = metadata[:deprecated]
+    raw_path_params = request.path_parameters
+
+    summary ||= route.requirements[:action]
+    tags ||= [route.requirements[:controller]&.classify].compact
+    # :controller and :action always exist. :format is added when routes is configured as such.
+    # TODO: Use .except(:controller, :action, :format) when we drop support for Ruby 2.x
+    raw_path_params = raw_path_params.slice(*(raw_path_params.keys - RSpec::OpenAPI.ignored_path_params))
+
+    summary ||= "#{request.method} #{path}"
+
+    [path, summary, tags, operation_id, required_request_params, raw_path_params, description, security, deprecated]
+  end
+
+  # @param [RSpec::ExampleGroups::*] context
+  def request_response(context)
+    [context.request, context.response]
+  end
+
+  # @param [ActionDispatch::Request] request
+  def find_rails_route(request, app: Rails.application, path_prefix: '')
+    app.routes.router.recognize(request) do |route, _parameters|
+      path = route.path.spec.to_s.delete_suffix('(.:format)')
+
+      if route.app.matches?(request)
+        if route.app.engine?
+          route, path = find_rails_route(request, app: route.app.app, path_prefix: path)
+          next if route.nil?
+        end
+
+        # Params are empty when it is Engine or Rack app.
+        # In that case, we can't handle parameters in path.
+        return [route, nil] if request.params.empty?
+
+        return [route, path_prefix + path]
+      end
+    end
+
+    nil
+  end
+end

data/lib/rspec/openapi/extractors.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Create namespace
+module RSpec::OpenAPI::Extractors
+end

data/lib/rspec/openapi/hash_helper.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+class << RSpec::OpenAPI::HashHelper = Object.new
+  def paths_to_all_fields(obj)
+    case obj
+    when Hash
+      obj.each.flat_map do |k, v|
+        k = k.to_sym
+        [[k]] + paths_to_all_fields(v).map { |x| [k, *x] }
+      end
+    when Array
+      obj.flat_map.with_index do |value, i|
+        [[i]] + paths_to_all_fields(value).map { |x| [i, *x] }
+      end
+    else
+      []
+    end
+  end
+
+  def matched_paths(obj, selector)
+    selector_parts = selector.split('.').map(&:to_sym)
+    paths_to_all_fields(obj).select do |key_parts|
+      key_parts.size == selector_parts.size && key_parts.zip(selector_parts).all? do |kp, sp|
+        kp == sp || (sp == :* && !kp.nil?)
+      end
+    end
+  end
+
+  def matched_paths_deeply_nested(obj, begin_selector, end_selector)
+    path_depth_sizes = paths_to_all_fields(obj).map(&:size).uniq
+    path_depth_sizes.map do |depth|
+      begin_selector_count = begin_selector.is_a?(Symbol) ? 0 : begin_selector.count('.')
+      end_selector_count = end_selector.is_a?(Symbol) ? 0 : end_selector.count('.')
+      diff = depth - begin_selector_count - end_selector_count
+      if diff >= 0
+        selector = "#{begin_selector}.#{'*.' * diff}#{end_selector}"
+        matched_paths(obj, selector)
+      else
+        []
+      end
+    end.flatten(1)
+  end
+end

data/lib/rspec/openapi/key_transformer.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+class << RSpec::OpenAPI::KeyTransformer = Object.new
+  def symbolize(value)
+    case value
+    when Hash
+      value.to_h { |k, v| [k.to_sym, symbolize(v)] }
+    when Array
+      value.map { |v| symbolize(v) }
+    else
+      value
+    end
+  end
+
+  def stringify(value)
+    case value
+    when Hash
+      value.to_h { |k, v| [k.to_s, stringify(v)] }
+    when Array
+      value.map { |v| stringify(v) }
+    else
+      value
+    end
+  end
+end

data/lib/rspec/openapi/minitest_hooks.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'minitest'
+
+module RSpec::OpenAPI::Minitest
+  Example = Struct.new(:context, :description, :metadata, :file_path)
+
+  module RunPatch
+    def run(*args)
+      result = super
+      if ENV['OPENAPI'] && self.class.openapi?
+        file_path = method(name).source_location.first
+        human_name = name.sub(/^test_/, '').gsub('_', ' ')
+        example = Example.new(self, human_name, {}, file_path)
+        path = RSpec::OpenAPI.path.then { |p| p.is_a?(Proc) ? p.call(example) : p }
+        record = RSpec::OpenAPI::RecordBuilder.build(self, example: example, extractor: SharedHooks.find_extractor)
+        RSpec::OpenAPI.path_records[path] << record if record
+      end
+      result
+    end
+  end
+
+  module ActivateOpenApiClassMethods
+    def self.prepended(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def openapi?
+        @openapi
+      end
+
+      def openapi!
+        @openapi = true
+      end
+    end
+  end
+end
+
+Minitest::Test.prepend RSpec::OpenAPI::Minitest::ActivateOpenApiClassMethods
+
+if ENV['OPENAPI']
+  Minitest::Test.prepend RSpec::OpenAPI::Minitest::RunPatch
+
+  Minitest.after_run do
+    result_recorder = RSpec::OpenAPI::ResultRecorder.new(RSpec::OpenAPI.path_records)
+    result_recorder.record_results!
+    puts result_recorder.error_message if result_recorder.errors?
+  end
+end

data/lib/rspec/openapi/record.rb

@@ -1,15 +1,25 @@
+# frozen_string_literal: true
+
 RSpec::OpenAPI::Record = Struct.new(
-  :method,                # @param [String]  - "GET"
+  :title,                 # @param [String]  - "API Documentation - Statuses"
+  :http_method,           # @param [String]  - "GET"
   :path,                  # @param [String]  - "/v1/status/:id"
   :path_params,           # @param [Hash]    - {:controller=>"v1/statuses", :action=>"create", :id=>"1"}
   :query_params,          # @param [Hash]    - {:query=>"string"}
   :request_params,        # @param [Hash]    - {:request=>"body"}
+  :required_request_params, # @param [Array]    - ["param1", "param2"]
   :request_content_type,  # @param [String]  - "application/json"
-  :controller,            # @param [String]  - "v1/statuses"
-  :action,                # @param [String]  - "show"
+  :request_headers,       # @param [Array]  - [["header_key1", "header_value1"], ["header_key2", "header_value2"]]
+  :summary,               # @param [String]  - "v1/statuses #show"
+  :tags,                  # @param [Array]   - ["Status"]
+  :operation_id,          # @param [String]   - "request-1234"
   :description,           # @param [String]  - "returns a status"
+  :security,              # @param [Array]  - [{securityScheme1: []}]
+  :deprecated,            # @param [Boolean] - true
   :status,                # @param [Integer] - 200
   :response_body,         # @param [Object]  - {"status" => "ok"}
+  :response_headers,      # @param [Array]  - [["header_key1", "header_value1"], ["header_key2", "header_value2"]]
   :response_content_type, # @param [String]  - "application/json"
+  :response_content_disposition, # @param [String]  - "inline"
   keyword_init: true,
 )

data/lib/rspec/openapi/record_builder.rb

@@ -1,38 +1,82 @@
+# frozen_string_literal: true
+
+require 'action_dispatch'
 require 'rspec/openapi/record'
 
 class << RSpec::OpenAPI::RecordBuilder = Object.new
   # @param [RSpec::ExampleGroups::*] context
   # @param [RSpec::Core::Example] example
-  # @return [RSpec::OpenAPI::Record]
-  def build(context, example:)
-    # TODO: Support Non-Rails frameworks
-    request = context.request
-    response = context.response
-    route = find_route(request)
+  # @return [RSpec::OpenAPI::Record,nil]
+  def build(context, example:, extractor:)
+    request, response = extractor.request_response(context)
+    return if request.nil?
+
+    title = RSpec::OpenAPI.title.then { |t| t.is_a?(Proc) ? t.call(example) : t }
+    path, summary, tags, operation_id, required_request_params, raw_path_params, description, security, deprecated =
+      extractor.request_attributes(request, example)
+
+    return if RSpec::OpenAPI.ignored_paths.any? { |ignored_path| path.match?(ignored_path) }
+
+    request_headers, response_headers = extract_headers(request, response)
 
     RSpec::OpenAPI::Record.new(
-      method: request.request_method,
-      path: route.path.spec.to_s.delete_suffix('(.:format)'),
-      path_params: request.path_parameters,
+      title: title,
+      http_method: request.method,
+      path: path,
+      path_params: raw_path_params,
       query_params: request.query_parameters,
-      request_params: request.request_parameters,
-      request_content_type: request.content_type,
-      controller: route.requirements[:controller],
-      action: route.requirements[:action],
-      description: example.description,
+      request_params: raw_request_params(request),
+      required_request_params: required_request_params,
+      request_content_type: request.media_type,
+      request_headers: request_headers,
+      summary: summary,
+      tags: tags,
+      operation_id: operation_id,
+      description: description,
+      security: security,
+      deprecated: deprecated,
       status: response.status,
-      response_body: response.parsed_body,
-      response_content_type: response.content_type,
+      response_body: safe_parse_body(response, response.media_type),
+      response_headers: response_headers,
+      response_content_type: response.media_type,
+      response_content_disposition: response.header['Content-Disposition'],
     ).freeze
   end
 
   private
 
-  # @param [ActionDispatch::Request] request
-  def find_route(request)
-    Rails.application.routes.router.recognize(request) do |route|
-      return route
+  def safe_parse_body(response, media_type)
+    # Use raw body, because Nokogiri-parsed HTML are modified (new lines injection, meta injection, and so on) :(
+    return response.body if media_type == 'text/html'
+
+    response.parsed_body
+  rescue JSON::ParserError
+    nil
+  end
+
+  def extract_headers(request, response)
+    request_headers = RSpec::OpenAPI.request_headers.each_with_object([]) do |header, headers_arr|
+      header_key = header.gsub('-', '_').upcase.to_sym
+
+      header_value = request.get_header(['HTTP', header_key].join('_')) ||
+                     request.get_header(header_key) ||
+                     request.get_header(header_key.to_s)
+      headers_arr << [header, header_value] if header_value
+    end
+    response_headers = RSpec::OpenAPI.response_headers.each_with_object([]) do |header, headers_arr|
+      header_key = header
+      header_value = response.headers[header_key]
+      headers_arr << [header_key, header_value] if header_value
     end
-    raise "No route matched for #{request.request_method} #{request.path_info}"
+    [request_headers, response_headers]
+  end
+
+  # workaround to get real request parameters
+  # because ActionController::ParamsWrapper overwrites request_parameters
+  def raw_request_params(request)
+    original = request.delete_header('action_dispatch.request.request_parameters')
+    request.request_parameters
+  ensure
+    request.set_header('action_dispatch.request.request_parameters', original)
   end
 end

data/lib/rspec/openapi/result_recorder.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+class RSpec::OpenAPI::ResultRecorder
+  def initialize(path_records)
+    @path_records = path_records
+    @error_records = {}
+  end
+
+  def record_results!
+    @path_records.each do |path, records|
+      # Look for a path-specific config file and run it.
+      config_file = File.join(File.dirname(path), RSpec::OpenAPI.config_filename)
+      begin
+        require config_file if File.exist?(config_file)
+      rescue StandardError => e
+        puts "WARNING: Unable to load #{config_file}: #{e}"
+      end
+
+      title = records.first.title
+      RSpec::OpenAPI::SchemaFile.new(path).edit do |spec|
+        schema = RSpec::OpenAPI::DefaultSchema.build(title)
+        schema[:info].merge!(RSpec::OpenAPI.info)
+        RSpec::OpenAPI::SchemaMerger.merge!(spec, schema)
+        new_from_zero = {}
+        records.each do |record|
+          record_schema = RSpec::OpenAPI::SchemaBuilder.build(record)
+          RSpec::OpenAPI::SchemaMerger.merge!(spec, record_schema)
+          RSpec::OpenAPI::SchemaMerger.merge!(new_from_zero, record_schema)
+        rescue StandardError, NotImplementedError => e # e.g. SchemaBuilder raises a NotImplementedError
+          @error_records[e] = record # Avoid failing the build
+        end
+        cleanup_schema!(new_from_zero, spec)
+        execute_post_process_hook(path, records, spec)
+      end
+    end
+  end
+
+  def errors?
+    @error_records.any?
+  end
+
+  def error_message
+    <<~ERR_MSG
+      RSpec::OpenAPI got errors building #{@error_records.size} requests
+
+      #{@error_records.map { |e, record| "#{e.inspect}: #{record.inspect}" }.join("\n")}
+    ERR_MSG
+  end
+
+  private
+
+  def execute_post_process_hook(path, records, spec)
+    RSpec::OpenAPI.post_process_hook.call(path, records, spec) if RSpec::OpenAPI.post_process_hook.is_a?(Proc)
+  end
+
+  def cleanup_schema!(new_from_zero, spec)
+    RSpec::OpenAPI::SchemaCleaner.cleanup_conflicting_security_parameters!(spec)
+    RSpec::OpenAPI::SchemaCleaner.cleanup!(spec, new_from_zero)
+    RSpec::OpenAPI::ComponentsUpdater.update!(spec, new_from_zero)
+    RSpec::OpenAPI::SchemaCleaner.cleanup_empty_required_array!(spec)
+    RSpec::OpenAPI::SchemaSorter.deep_sort!(spec)
+  end
+end

data/lib/rspec/openapi/rspec_hooks.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'rspec/core'
+
+RSpec.configuration.after(:each) do |example|
+  if RSpec::OpenAPI.example_types.include?(example.metadata[:type]) && example.metadata[:openapi] != false
+    path = RSpec::OpenAPI.path.then { |p| p.is_a?(Proc) ? p.call(example) : p }
+    record = RSpec::OpenAPI::RecordBuilder.build(self, example: example, extractor: SharedHooks.find_extractor)
+    RSpec::OpenAPI.path_records[path] << record if record
+  end
+end
+
+RSpec.configuration.after(:suite) do
+  result_recorder = RSpec::OpenAPI::ResultRecorder.new(RSpec::OpenAPI.path_records)
+  result_recorder.record_results!
+  if result_recorder.errors?
+    error_message = result_recorder.error_message
+    colorizer = RSpec::Core::Formatters::ConsoleCodes
+    RSpec.configuration.reporter.message colorizer.wrap(error_message, :failure)
+  end
+end