rspec-rails-api 0.1.0

data/lib/rspec/rails/api/matchers.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'active_support/hash_with_indifferent_access'
+
+require 'rspec/rails/api/utils'
+
+# FIXME: Split the matcher in something else; it's too messy.
+RSpec::Matchers.define :have_many do |expected|
+  match do |actual|
+    @actual = actual
+    @actual = JSON.parse(actual.body) if actual.respond_to? :body
+
+    raise "Response is not an array: #{@actual.class}" unless @actual.is_a? Array
+    raise 'Response has no item to compare with' unless @actual.count.positive?
+
+    # Check every entry
+    ok = true
+    @actual.each do |item|
+      ok = false unless RSpec::Rails::Api::Utils.validate_object_structure item, expected
+    end
+
+    ok
+  end
+
+  diffable
+end
+
+# FIXME: Split the matcher in something else; it's too messy.
+RSpec::Matchers.define :have_one do |expected|
+  match do |actual|
+    @actual = actual
+    @actual = JSON.parse(actual.body) if actual.respond_to? :body
+
+    raise "Response is not a hash: #{@actual.class}" unless @actual.is_a? Hash
+
+    RSpec::Rails::Api::Utils.validate_object_structure @actual, expected
+  end
+
+  diffable
+end

data/lib/rspec/rails/api/metadata.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require 'rspec/rails/api/utils'
+require 'rspec/rails/api/open_api_renderer'
+require 'rspec/rails/api/entity_config'
+
+module RSpec
+  module Rails
+    module Api
+      # Handles contexts and examples metadatas.
+      class Metadata # rubocop:disable Metrics/ClassLength
+        attr_reader :entities, :resources, :current_resource
+
+        def initialize
+          @resources = {}
+          @entities  = {}
+          # Only used when building metadata during RSpec boot
+          @current_resource = nil
+          @current_method   = nil
+          @current_url      = nil
+          @current_code     = nil
+        end
+
+        def add_resource(name, description)
+          @resources[name.to_sym] = { description: description, paths: {} }
+          @current_resource       = name.to_sym
+        end
+
+        def add_entity(type, fields)
+          Utils.deep_set(@resources,
+                         "#{@current_resource}.entities.#{type}",
+                         EntityConfig.new(fields))
+        end
+
+        def add_path_params(fields) # rubocop:disable Metrics/MethodLength
+          check_current_context :resource, :url
+
+          chunks = @current_url.split('?')
+
+          fields.each do |name, field|
+            valid_attribute = Utils.check_attribute_type(field[:type], except: %i[array object])
+            raise "Field type not allowed: #{field[:type]}" unless valid_attribute
+
+            scope = path_param_scope(chunks, name)
+            Utils.deep_set(@resources, "#{@current_resource}.paths.#{@current_url}.path_params.#{name}",
+                           description: field[:description] || nil,
+                           type:        field[:type] || nil,
+                           required:    field[:required] || true,
+                           scope:       scope)
+          end
+        end
+
+        # Fields should be something like:
+        #   id:   {type: :number, description: 'Something'},
+        #   name: {type: string, description: 'Something'}
+        # Ex. with sub elements:
+        #   id: {type: :number, description: 'Something'},
+        #   something: {type: :object, description: 'Something', properties: {
+        #     property: {type: :string, description: 'Something'},
+        #     ...
+        #   }}
+        def add_request_params(fields)
+          check_current_context :resource, :url, :method
+
+          params = organize_params fields
+          Utils.deep_set(@resources,
+                         "#{@current_resource}.paths.#{@current_url}.actions.#{@current_method}.params",
+                         params)
+        end
+
+        def add_action(method, url, description)
+          check_current_context :resource
+
+          Utils.deep_set(@resources, "#{@current_resource}.paths.#{url}.actions.#{method}",
+                         description: description,
+                         statuses:    {},
+                         params:      [])
+
+          @current_url    = url
+          @current_method = method
+        end
+
+        # rubocop:disable Metrics/LineLength
+        def add_status_code(status_code, description)
+          check_current_context :resource, :url, :method
+
+          Utils.deep_set(@resources,
+                         "#{@current_resource}.paths.#{@current_url}.actions.#{@current_method}.statuses.#{status_code}",
+                         description: description,
+                         example:     { response: nil })
+          @current_code = status_code
+        end
+        # rubocop:enable Metrics/LineLength
+
+        # rubocop:disable Metrics/ParameterLists
+        def add_request_example(url: nil, action: nil, status_code: nil, response: nil, path_params: nil, params: nil)
+          resource = nil
+          @resources.each do |key, res|
+            resource = key if Utils.deep_get(res, "paths.#{url}.actions.#{action}.statuses.#{status_code}")
+          end
+
+          raise "Resource not found for #{action.upcase} #{url}" unless resource
+
+          Utils.deep_set(@resources,
+                         "#{resource}.paths.#{url}.actions.#{action}.statuses.#{status_code}.example",
+                         path_params: path_params,
+                         params:      params,
+                         response:    response)
+        end
+        # rubocop:enable Metrics/ParameterLists
+
+        def to_h
+          {
+            resources: @resources,
+            entities:  @entities,
+          }
+        end
+
+        private
+
+        # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/MethodLength, Style/GuardClause
+        def check_current_context(*scope)
+          scope ||= []
+          if scope.include?(:resource)
+            raise 'No resource declared' unless @current_resource
+          end
+          if scope.include?(:method)
+            raise 'No action declared' unless @current_method
+          end
+          if scope.include?(:url)
+            raise 'No url declared' unless @current_url
+          end
+          if scope.include?(:code)
+            raise 'No status code declared' unless @current_code
+          end
+        end
+
+        # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/MethodLength, Style/GuardClause
+
+        def path_param_scope(url_chunks, name)
+          if /:#{name}/ =~ url_chunks[0]
+            :path
+          elsif url_chunks[1] && /:#{name}/ =~ url_chunks[1]
+            :query
+          else
+            raise "#{name} not found in URL #{@current_url}"
+          end
+        end
+
+        def organize_params(fields) # rubocop:disable Metrics/AbcSize
+          out      = { properties: {} }
+          required = []
+          fields.each do |name, field|
+            allowed_type = %i[array object].include?(field[:type]) || PARAM_TYPES.key?(field[:type])
+            raise "Field type not allowed: #{field[:type]}" unless allowed_type
+
+            required.push name.to_s if field[:required]
+
+            out[:properties][name] = fill_request_param field
+          end
+          out[:required] = required if required.count.positive?
+          out
+        end
+
+        def fill_request_param(field)
+          if field[:type] && field[:type] == :object
+            organize_params field[:properties] if field[:properties]
+          else
+            {
+              type:        field[:type].to_s,
+              description: field[:description] || nil,
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rspec/rails/api/open_api_renderer.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require 'rspec/rails/api/utils'
+require 'active_support'
+
+module RSpec
+  module Rails
+    module Api
+      # Class to render metadatas.
+      # Example:
+      #   ```rb
+      #   renderer = RSpec::Rails::Api::OpenApiRenderer.new
+      #   renderer.merge_context(example_context)
+      #   renderer.write_files
+      #   ```
+      class OpenApiRenderer # rubocop:disable Metrics/ClassLength
+        def initialize
+          @metadata = {
+            resources: {},
+            entities:  {},
+          }
+          @api_infos = {}
+          @api_servers = {}
+          @api_paths = {}
+          @api_components = {}
+          @api_tags       = []
+        end
+
+        def merge_context(context)
+          @metadata[:resources].deep_merge! context[:resources]
+          @metadata[:entities].deep_merge! context[:entities]
+        end
+
+        def write_files
+          content = prepare_metadata
+          File.write ::Rails.root.join('tmp', 'out.yaml'), content.to_yaml
+          File.write ::Rails.root.join('tmp', 'out.json'), content.to_json
+        end
+
+        def prepare_metadata
+          # Example: https://github.com/OAI/OpenAPI-Specification/blob/master/examples/v3.0/petstore-expanded.yaml
+          extract_metadatas
+          {
+            openapi:    '3.0.0',
+            info:       @api_infos,
+            servers:    @api_servers,
+            paths:      @api_paths,
+            components: @api_components,
+            tags:       @api_tags,
+          }.deep_stringify_keys
+        end
+
+        private
+
+        def extract_metadatas
+          extract_from_resources
+          extract_api_infos
+          extract_api_servers
+        end
+
+        def extract_from_resources
+          @metadata[:resources].each do |resource_key, resource|
+            @api_tags.push(
+              name:        resource_key.to_s,
+              description: resource[:description]
+            )
+            process_resource resource: resource_key, resource_config: resource
+          end
+        end
+
+        def process_resource(resource: nil, resource_config: nil) # rubocop:disable Metrics/MethodLength
+          resource_config[:paths].each do |path_key, path|
+            url        = path_with_params path_key.to_s
+            actions    = {}
+            parameters = path.key?(:path_params) ? process_path_params(path[:path_params]) : []
+
+            path[:actions].each_key do |action|
+              next unless %i[get post put patch delete].include? action
+
+              actions[action] = process_action resource:      resource,
+                                               path:          path_key,
+                                               path_config:   path,
+                                               action_config: action,
+                                               parameters:    parameters
+            end
+
+            @api_paths[url] = actions
+          end
+        end
+
+        def process_path_params(params)
+          parameters = []
+          params.each do |name, param|
+            parameters.push process_path_param name, param
+          end
+
+          parameters
+        end
+
+        def process_path_param(name, param) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+          parameter = {
+            name:        name.to_s,
+            description: param[:description],
+            required:    param[:required] || true,
+            in:          param[:scope].to_s,
+            schema:      {
+              type: PARAM_TYPES[param[:type]][:type],
+            },
+          }
+
+          parameter[:schema][:format] = PARAM_TYPES[param[:type]][:format] if PARAM_TYPES[param[:type]][:format]
+
+          parameter
+        end
+
+        # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        def process_action(resource: nil, path: nil, path_config: nil, action_config: nil, parameters: nil)
+          responses    = {}
+          request_body = nil
+
+          if %i[post put patch].include? action_config
+            if path_config[:actions][action_config][:params].keys.count.positive?
+              schema       = path_config[:actions][action_config][:params]
+              schema_ref   = escape_operation_id("#{action_config}_#{path}")
+              request_body = process_request_body schema: schema, ref: schema_ref
+            end
+          end
+
+          path_config[:actions][action_config][:statuses].each do |status_key, status|
+            content               = status[:example][:response]
+            responses[status_key] = process_response status: status_key, status_config: status, content: content
+          end
+
+          description          = path_config[:actions][action_config][:description]
+          action               = {
+            description: description,
+            operationId: "#{resource} #{description}".downcase.gsub(/[^\w]/, '_'),
+            parameters:  parameters,
+            responses:   responses,
+            tags:        [resource.to_s],
+          }
+
+          action[:requestBody] = request_body if request_body
+
+          action
+        end
+
+        # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+        def process_request_body(schema: nil, ref: nil)
+          Utils.deep_set @api_components, "schemas.#{ref}", schema
+          {
+            # description: '',
+            required: true,
+            content:  {
+              'application/json' => {
+                schema: { '$ref' => "#/components/schemas/#{ref}" },
+              },
+            },
+          }
+        end
+
+        def process_response(status: nil, status_config: nil, content: nil)
+          response = {
+            description: status_config[:description],
+          }
+
+          return response unless status.to_s != '204' && content # No content
+
+          response[:content] = {
+            'application/json': {
+              examples: { default: { value: JSON.pretty_generate(JSON.parse(content)) } },
+            },
+          }
+
+          response
+        end
+
+        def path_with_params(string)
+          string.gsub(/(?::(\w*))/) do |e|
+            "{#{e.sub(':', '')}}"
+          end
+        end
+
+        def escape_operation_id(string)
+          string.downcase.gsub(/[^\w]+/, '_')
+        end
+
+        def extract_api_infos # rubocop:disable Metrics/MethodLength
+          @api_infos = {
+            title:          'Some sample app',
+            version:        '1.0',
+            description:    'A nice API',
+            termsOfService: 'https://example.com/tos',
+            contact:        {
+              name:  'API Team',
+              email: 'api-team@example.com',
+              url:   'http://example.com',
+            },
+            license:        {
+              name: 'Apache 2',
+              url:  'https://url-to-license.com',
+            },
+          }
+        end
+
+        def extract_api_servers
+          @api_servers = [
+            { url: 'http://api.example.com' },
+          ]
+        end
+      end
+    end
+  end
+end

data/lib/rspec/rails/api/utils.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'active_support/hash_with_indifferent_access'
+
+module RSpec
+  module Rails
+    module Api
+      # Helper methods
+      class Utils
+        def self.deep_get(hash, path)
+          path.split('.').inject(hash) do |sub_hash, key|
+            return nil unless sub_hash.is_a?(Hash) && sub_hash.key?(key.to_sym)
+
+            sub_hash[key.to_sym]
+          end
+        end
+
+        def self.deep_set(hash, path, value)
+          path = path.split('.') unless path.is_a? Array
+
+          return value if path.count.zero?
+
+          current_key       = path.shift.to_sym
+          hash[current_key] = {} unless hash[current_key].is_a?(Hash)
+          hash[current_key] = deep_set(hash[current_key], path, value)
+
+          hash
+        end
+
+        def self.check_value_type(type, value) # rubocop:disable Metrics/CyclomaticComplexity
+          return true if type == :boolean && (value.is_a?(TrueClass) || value.is_a?(FalseClass))
+          return true if type == :array && value.is_a?(Array)
+
+          raise "Unknown type #{type}" unless PARAM_TYPES.key? type
+
+          value.is_a? PARAM_TYPES[type][:class]
+        end
+
+        def self.validate_object_structure(actual, expected)
+          # Check keys
+          return false unless same_keys? actual, expected
+
+          expected.each_key do |key|
+            next unless expected[key][:required]
+
+            expected_type       = expected[key][:type]
+            expected_attributes = expected[key][:attributes]
+
+            # Type
+            return false unless check_value_type expected_type, actual[key.to_s]
+
+            # Deep object ?
+            return false unless validate_deep_object expected_type, expected_attributes, actual[key.to_s]
+          end
+
+          true
+        end
+
+        # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength
+        def self.validate_deep_object(expected_type, expected_attributes, actual)
+          if %i[object array].include?(expected_type) && expected_attributes.is_a?(Hash)
+            case expected_type
+            when :object
+              return false unless validate_object_structure actual, expected_attributes
+            when :array
+              actual.each do |array_entry|
+                return false unless validate_object_structure array_entry, expected_attributes
+              end
+            end
+          end
+
+          true
+        end
+        # rubocop:enable Metrics/CyclomaticComplexity, Metrics/MethodLength
+
+        def self.same_keys?(actual, expected)
+          optional = expected.reject { |_key, value| value[:required] }.keys
+          actual.symbolize_keys.keys.sort - optional == expected.keys.sort - optional
+        end
+
+        def self.check_attribute_type(type, except: [])
+          keys = PARAM_TYPES.keys.reject { |key| except.include? key }
+          keys.include?(type)
+        end
+      end
+    end
+  end
+end