ropen_pi 0.2.0

data/lib/ropen_pi/specs/example_helpers.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'ropen_pi/specs/request_factory'
+require 'ropen_pi/specs/response_validator'
+
+module RopenPi::Specs::ExampleHelpers
+  def submit_request(metadata)
+    request = RopenPi::Specs::RequestFactory.new.build_request(metadata, self)
+    send(
+      request[:verb],
+      request[:path],
+      params: request[:payload],
+      headers: request[:headers]
+    )
+  end
+
+  def assert_response_matches_metadata(metadata)
+    RopenPi::Specs::ResponseValidator.new.validate!(metadata, response)
+  end
+end

data/lib/ropen_pi/specs/extended_schema.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'json-schema'
+
+module RopenPi
+  module Specs
+    class ExtendedTypeAttribute < JSON::Schema::TypeV4Attribute
+      def self.validate(current_schema, data, fragments, processor, validator, options = {})
+        schema_nullable = (current_schema.schema['nullable'] == true || current_schema.schema['x-nullable'] == true)
+
+        return if data.nil? && schema_nullable
+
+        super
+      end
+    end
+
+    class ExtendedSchema < JSON::Schema::Draft4
+      def initialize
+        super
+
+        @attributes['type'] = ExtendedTypeAttribute
+        temp_uri = 'http://tempuri.org/rswag/specs/extended_schema'
+        @uri = URI.parse(temp_uri)
+        @names = [temp_uri]
+      end
+    end
+
+    JSON::Validator.register_validator(ExtendedSchema.new)
+  end
+end

data/lib/ropen_pi/specs/open_api_formatter.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/hash/deep_merge'
+require 'ropen_pi_helper'
+require 'ropen_pi/specs/writer'
+
+class RopenPi::Specs::OpenApiFormatter
+  ::RSpec::Core::Formatters.register self, :example_group_finished, :stop
+
+  def initialize(output, config = ::RopenPi::Specs.config)
+    @output = output
+    @config = config
+
+    @output.puts 'Generating OpenAPI docs ...'
+  end
+
+  def example_group_finished(notification)
+    metadata = notification.group.metadata
+
+    return unless metadata.key?(:response)
+
+    open_api_doc = @config.get_doc(metadata[:doc])
+    open_api_doc.deep_merge!(metadata_to_open_api(metadata))
+  end
+
+  def stop(_notification = nil)
+    @config.open_api_docs.each do |url_path, doc|
+      # remove 2.0 parameters
+      doc[:paths]&.each do |_k, v|
+        v.each do |_verb, value|
+          merge_clean(value)
+        end
+      end
+
+      write(doc, url_path)
+    end
+  end
+
+  private
+
+  def write(doc, url_path)
+    file_path = File.join(@config.root_dir, url_path)
+    dirname = File.dirname(file_path)
+    FileUtils.mkdir_p(dirname) unless File.exist?(dirname)
+
+    File.open(file_path, 'w') do |file|
+      writer = RopenPi::Specs::Writer.new(@config.open_api_output_format)
+      file.write(writer.write(doc))
+    end
+
+    @output.puts "OpenAPI doc generated at #{file_path}"
+  end
+
+  def merge_clean(value)
+    is_hash = value.is_a?(Hash)
+    if is_hash && value.dig(:parameters)
+      schema_param = value&.dig(:parameters)&.find { |p| p[:in] == :body && p[:schema] }
+
+      value[:requestBody][:content][RopenPi::APP_JSON].merge!(schema: schema_param[:schema]) \
+        if value && schema_param && value&.dig(:requestBody, :content, RopenPi::APP_JSON)
+
+      value[:parameters].reject! { |p| p[:in] == :body || p[:in] == :formData }
+      value[:parameters].each { |p| p.delete(:type) }
+      value[:headers]&.each { |p| p.delete(:type) }
+    end
+
+    value.delete(:consumes) if is_hash && value.dig(:consumes)
+    value.delete(:produces) if is_hash && value.dig(:produces)
+  end
+
+  def metadata_to_open_api(metadata)
+    response_code = metadata[:response][:code]
+    response = metadata[:response].reject { |k, _v| k == :code }
+
+    app_json = RopenPi::APP_JSON
+
+    # need to merge in to response
+    if response[:examples]&.dig(app_json)
+      example = response[:examples].dig(app_json).dup
+      schema = response.dig(:content, app_json, :schema)
+
+      new_hash = { example: example }
+      new_hash[:schema] = schema if schema
+
+      response.merge!(content: { app_json => new_hash })
+      response.delete(:examples)
+    end
+
+    verb = metadata[:operation][:verb]
+    operation = metadata[:operation].reject { |k, _v| k == :verb }
+                                    .merge(responses: { response_code => response })
+
+    path_template = metadata[:path_item][:template]
+
+    path_item = metadata[:path_item].reject { |k, _v| k == :template }
+                                    .merge(verb => operation)
+
+    { paths: { path_template => path_item } }
+  end
+end

data/lib/ropen_pi/specs/railtie.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class RopenPi::Specs::Railtie < ::Rails::Railtie
+  rake_tasks do
+    load File.expand_path('../../tasks/ropen_pi.rake', __dir__)
+  end
+end

data/lib/ropen_pi/specs/request_factory.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/hash/slice'
+require 'active_support/core_ext/hash/conversions'
+require 'json'
+
+class RopenPi::Specs::RequestFactory
+  def initialize(config = ::RopenPi::Specs.config)
+    @config = config
+  end
+
+  def build_request(metadata, example)
+    open_api_doc = @config.get_doc(metadata[:doc])
+    parameters = expand_parameters(metadata, open_api_doc, example)
+
+    {}.tap do |request|
+      add_verb(request, metadata)
+      add_headers(request, metadata, open_api_doc, parameters, example)
+      add_path(request, metadata, open_api_doc, parameters, example)
+      add_payload(request, parameters, example)
+    end
+  end
+
+  private
+
+  def expand_parameters(metadata, open_api_doc, example)
+    operation_params = metadata[:operation][:parameters] || []
+    path_item_params = metadata[:path_item][:parameters] || []
+    security_params = derive_security_params(metadata, open_api_doc)
+
+    # NOTE: Use of + instead of concat to avoid mutation of the metadata object
+    (operation_params + path_item_params + security_params)
+      .map { |p| referenced_parameter(p, open_api_doc) }
+      .uniq { |p| p[:name] }
+      .select { |p| example.respond_to?(p[:name]) }
+  end
+
+  # to be able to use either '$ref' => '...' or '$ref': ... syntax
+  def referenced_parameter(parameter, open_api_doc)
+    ref_key = '$ref'
+
+    param = if parameter.key?(ref_key)
+              parameter.fetch(ref_key, nil)
+            else
+              parameter.fetch(ref_key.to_sym, nil)
+            end
+
+    return parameter if param.nil?
+
+    resolve_parameter(param, open_api_doc)
+  end
+
+  def derive_security_params(metadata, open_api_doc)
+    requirements = metadata[:operation][:security] || open_api_doc[:security] || []
+    scheme_names = requirements.flat_map(&:keys)
+    components = open_api_doc[:components] || {}
+    schemes = (components[:securitySchemes] || {}).slice(*scheme_names).values
+
+    schemes.map do |scheme|
+      param = scheme[:type] == :apiKey ? scheme.slice(:name, :in) : { name: 'Authorization', in: :header }
+      param.merge(type: :string, required: requirements.one?)
+    end
+  end
+
+  def resolve_parameter(ref, open_api_doc)
+    key = ref.sub('#/components/parameters/', '').to_sym
+    definitions = open_api_doc.dig(:components, :parameters)
+    raise "Referenced parameter '#{ref}' must be defined" unless definitions && definitions[key]
+
+    definitions[key]
+  end
+
+  def add_verb(request, metadata)
+    request[:verb] = metadata[:operation][:verb]
+  end
+
+  def add_path(request, metadata, open_api_doc, parameters, example)
+    template = (open_api_doc[:basePath] || '') + metadata[:path_item][:template]
+
+    in_path = parameters.select { |p| p[:in].to_sym == :path }
+    in_query = parameters.select { |p| p[:in].to_sym == :query }
+
+    request[:path] = template.tap do |inner_template|
+      in_path.each do |p|
+        inner_template.gsub!("{#{p[:name]}}", example.send(p[:name]).to_s)
+      end
+
+      in_query.each.with_index do |p, i|
+        inner_template.concat(i.zero? ? '?' : '&')
+        inner_template.concat(build_query_string_part(p, example.send(p[:name])))
+      end
+    end
+  end
+
+  def build_query_string_part(param, value)
+    name = param[:name]
+    "#{name}=#{value}" # this needs refactoring for collections
+
+    # all of this is deprecated and needs reimplementation
+    # case param[:collectionFormat]
+    # when :ssv
+    #   "#{name}=#{value.join(' ')}"
+    # when :tsv
+    #   "#{name}=#{value.join('\t')}"
+    # when :pipes
+    #   "#{name}=#{value.join('|')}"
+    # when :multi
+    #   value.map { |v| "#{name}=#{v}" }.join('&')
+    # else
+    #   "#{name}=#{value.join(',')}" # csv is default
+    # end
+  end
+
+  def add_headers(request, metadata, open_api_doc, parameters, example)
+    tuples = parameters.select { |p| p[:in] == :header }
+                       .map { |p| [p[:name], example.send(p[:name]).to_s] }
+    # Accept header
+    produces = metadata[:operation][:produces] || open_api_doc[:produces]
+    if produces
+      accept = example.respond_to?(:Accept) ? example.send(:Accept) : produces.first
+      tuples << ['Accept', accept]
+    end
+
+    # Content-Type header
+    consumes = metadata[:operation][:consumes] || open_api_doc[:consumes]
+    if consumes
+      content_type = example.respond_to?(:'Content-Type') ? example.send(:'Content-Type') : consumes.first
+      tuples << ['Content-Type', content_type]
+    end
+
+    # Rails test infrastructure requires rackified headers
+    rackified_tuples = tuples.map do |pair|
+      [
+        case pair[0]
+        when 'Accept' then 'HTTP_ACCEPT'
+        when 'Content-Type' then 'CONTENT_TYPE'
+        when 'Authorization' then 'HTTP_AUTHORIZATION'
+        else pair[0]
+        end,
+        pair[1]
+      ]
+    end
+
+    request[:headers] = Hash[rackified_tuples]
+  end
+
+  def add_payload(request, parameters, example)
+    content_type = request[:headers]['CONTENT_TYPE']
+    return if content_type.nil?
+
+    request[:payload] = if ['application/x-www-form-urlencoded', 'multipart/form-data'].include?(content_type)
+                          build_form_payload(parameters, example)
+                        else
+                          build_json_payload(parameters, example)
+                        end
+  end
+
+  def build_form_payload(parameters, example)
+    # See http://seejohncode.com/2012/04/29/quick-tip-testing-multipart-uploads-with-rspec/
+    # Rather that serializing with the appropriate encoding (e.g. multipart/form-data),
+    # Rails test infrastructure allows us to send the values directly as a hash
+    # PROS: simple to implement, CONS: serialization/deserialization is bypassed in test
+    tuples = parameters.select { |p| p[:in] == :formData }
+                        .map { |p| [p[:name], example.send(p[:name])] }
+    Hash[tuples]
+  end
+
+  def build_json_payload(parameters, example)
+    body_param = parameters.select { |p| p[:in] == :body && p[:name].is_a?(Symbol) }.first
+    return nil unless body_param
+
+    source_body_param = example.send(body_param[:name]) \
+      if body_param[:name] && example.respond_to?(body_param[:name])
+
+    source_body_param ||= body_param[:param_value]
+    source_body_param ? source_body_param.to_json : nil
+  end
+end

data/lib/ropen_pi/specs/response_validator.rb

@@ -0,0 +1,67 @@
+  # frozen_string_literal: true
+
+require 'active_support/core_ext/hash/slice'
+require 'json-schema'
+require 'json'
+require 'ropen_pi/specs/extended_schema'
+
+class RopenPi::Specs::ResponseValidator
+  def initialize(config = ::RopenPi::Specs.config)
+    @config = config
+  end
+
+  def validate!(metadata, response)
+    open_api_doc = @config.get_doc(metadata[:doc])
+
+    validate_code!(metadata, response)
+    validate_headers!(metadata, response.headers)
+    validate_body!(metadata, open_api_doc, response.body)
+  end
+
+  private
+
+  def validate_code!(metadata, response)
+    expected = metadata[:response][:code].to_s
+
+    # rubocop:disable Style/GuardClause
+    if response.code != expected
+      raise RopenPi::Specs::UnexpectedResponse,
+            "Expected response code '#{response.code}' to match '#{expected}'\n" \
+            "Response body: #{response.body}"
+    end
+    # rubocop:enable Style/GuardClause
+  end
+
+  def validate_headers!(metadata, headers)
+    expected = (metadata[:response][:headers] || {}).keys
+    expected.each do |name|
+      raise RopenPi::Specs::UnexpectedResponse, "Expected response header #{name} to be present" \
+        if headers[name.to_s].nil?
+    end
+  end
+
+  def validate_body!(metadata, open_api_doc, body)
+    test_schemas = extract_schemas(metadata)
+    return if test_schemas.nil? || test_schemas.empty?
+
+    components = open_api_doc[:components] || {}
+    components_schemas = { components: components }
+    # response_schema
+    validation_schema = test_schemas[:schema].merge('$schema' => 'http://tempuri.org/rswag/specs/extended_schema')
+                                             .merge(components_schemas)
+
+    errors = JSON::Validator.fully_validate(validation_schema, body)
+    raise RopenPi::Specs::UnexpectedResponse, "Expected response body to match schema: #{errors[0]}" if errors.any?
+  end
+
+  def extract_schemas(metadata)
+    metadata[:operation] = { produces: [] } if metadata[:operation].nil?
+    produces = Array(metadata[:operation][:produces])
+
+    producer_content = produces.first || 'application/json'
+    response_content = metadata[:response][:content] || { producer_content => {} }
+    response_content[producer_content]
+  end
+end
+
+class RopenPi::Specs::UnexpectedResponse < StandardError; end

data/lib/ropen_pi/specs/writer.rb

@@ -0,0 +1,35 @@
+module RopenPi::Specs
+  # concrete
+  class Writer
+    # strategies
+    module Json
+      def self.convert(doc)
+        JSON.pretty_generate(doc)
+      end
+    end
+
+    module Yml
+      require 'active_support/core_ext/hash/keys'
+
+      def self.convert(doc)
+        doc.deep_stringify_keys!
+        doc.deep_transform_values { |value| value.to_s if value.is_a?(Symbol) }
+
+        doc.to_yaml
+      end
+    end
+
+    def initialize(open_api_output_format)
+      @output_format = open_api_output_format
+    end
+
+    def write(doc)
+      if @output_format == :yaml || @output_format == :yml
+        Yml.convert(doc)
+      else
+        # this is by any means the default
+        Json.convert(doc)
+      end
+    end
+  end
+end

data/lib/ropen_pi/version.rb

@@ -0,0 +1,4 @@
+module RopenPi
+  VERSION = '0.2.0'.freeze
+  APP_JSON = 'application/json'.freeze
+end