rspec-rails-api 0.4.0 → 0.6.0

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

@@ -6,7 +6,7 @@ require 'active_support'
 module RSpec
   module Rails
     module Api
-      # Class to render metadatas.
+      # Class to render metadata.
       # Example:
       #   ```rb
       #   renderer = RSpec::Rails::Api::OpenApiRenderer.new
@@ -15,16 +15,36 @@ module RSpec
       #   ```
       class OpenApiRenderer # rubocop:disable Metrics/ClassLength
         attr_writer :api_servers, :api_title, :api_version, :api_description, :api_tos
+        attr_reader :redactables
 
         def initialize
-          @metadata = { resources: {}, entities: {} }
-          @api_infos = {}
-          @api_servers = []
-          @api_paths = {}
+          @metadata       = { resources: {}, entities: {} }
+          @api_infos      = {}
+          @api_servers    = []
+          @api_paths      = {}
           @api_components = {}
           @api_tags       = []
           @api_contact    = {}
           @api_license    = {}
+          @api_security   = {}
+          @redactables    = {}
+        end
+
+        def redact_responses(pairs)
+          @redactables = pairs
+        end
+
+        ##
+        # Adds a security scheme definition to the API documentation
+        #
+        # @param reference  [Symbol] Reference to use in the tests
+        # @param name       [String] Human friendly name
+        # @param definition [Hash]   Security scheme definition as per https://swagger.io/specification/#security-scheme-object
+        def add_security_scheme(reference, name, definition)
+          raise "Security scheme #{reference} is already defined" if @api_security.key? reference
+
+          definition[:name] = name
+          @api_security[reference] = definition
         end
 
         ##
@@ -35,11 +55,10 @@ module RSpec
         #
         # @return [void
         def merge_context(context, dump_metadata: false)
-          @metadata[:resources].deep_merge! context[:resources]
-          @metadata[:entities].deep_merge! context[:entities]
+          @metadata[:resources].deep_merge! context.respond_to?(:resources) ? context.resources : context[:resources]
 
           # Save context for debug and fixtures
-          File.write ::Rails.root.join('tmp', 'rra_metadata.yaml'), context.to_yaml if dump_metadata
+          File.write ::Rails.root.join('tmp', 'rra_metadata.yaml'), @metadata.to_yaml if dump_metadata
         end
 
         ##
@@ -50,14 +69,20 @@ module RSpec
         #
         # @return [void]
         def write_files(path = nil, only: %i[yaml json])
+          return unless write_file? RSpec.world.filtered_examples
+
           path ||= ::Rails.root.join('tmp', 'rspec_api_rails')
 
-          file_types = %i[yaml json]
+          metadata = prepare_metadata
 
+          file_types = %i[yaml json]
           only.each do |type|
             next unless file_types.include? type
 
-            File.write "#{path}.#{type}", prepare_metadata.send("to_#{type}")
+            data = metadata.to_yaml if type == :yaml
+            data = JSON.pretty_generate(metadata) if type == :json
+
+            File.write "#{path}.#{type}", data
           end
         end
 
@@ -66,7 +91,7 @@ module RSpec
         #
         # @return [Hash] The OpenAPI structure
         def prepare_metadata
-          extract_metadatas
+          extract_metadata
           # Example: https://github.com/OAI/OpenAPI-Specification/blob/master/examples/v3.0/petstore-expanded.yaml
           hash = {
             openapi:    '3.0.0',
@@ -76,7 +101,7 @@ module RSpec
             components: @api_components,
             tags:       @api_tags,
           }
-          JSON.parse(JSON.pretty_generate(hash))
+          JSON.parse(hash.to_json)
         end
 
         ##
@@ -107,29 +132,50 @@ module RSpec
 
         private
 
+        def write_file?(examples)
+          acceptance_examples = examples.values.flatten.filter do |e|
+            e.metadata[:type] == :acceptance
+          end
+          unless acceptance_examples.none?(&:exception)
+            puts "\n\e[00;31mSome acceptance tests failed. OpenApi specification file was not updated.\n\e[00m"
+            return false
+          end
+
+          true
+        end
+
         ##
         # Extracts metadata for rendering
         #
         # @return [void]
-        def extract_metadatas
-          extract_from_resources
+        def extract_metadata
+          extract_security
           api_infos
           api_servers
+          global_entities
+          extract_from_resources
+        end
+
+        ##
+        # Extracts metadata from security schemes for rendering
+        #
+        # @return [void]
+        def extract_security
+          return unless @api_security.keys.count.positive?
+
+          @api_components['securitySchemes'] = @api_security
         end
 
         ##
         # Extracts metadata from resources for rendering
         #
         # @return [void]
-        def extract_from_resources # rubocop:disable Metrics/MethodLength
+        def extract_from_resources
           @api_components[:schemas] ||= {}
           @metadata[:resources].each do |resource_key, resource|
-            resource[:entities].each do |name, entity|
-              @api_components[:schemas][name] = process_entity(entity)
-            end
             @api_tags.push(
               name:        resource_key.to_s,
-              description: resource[:description]
+              description: resource[:description].presence&.strip || ''
             )
             process_resource resource: resource_key, resource_config: resource
           end
@@ -177,24 +223,29 @@ module RSpec
           parameters
         end
 
-        def process_entity(entity) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        def process_entity(entity) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
           schema = {
             properties: {},
           }
           required = []
           entity.fields.each do |name, field|
             property = {
-              description: field.description,
+              description: field.description.presence&.strip || '',
               type:        PARAM_TYPES[field.type][:type],
             }
-            property[:format]         = PARAM_TYPES[field.type][:format] if PARAM_TYPES[field.type][:format]
-            schema[:properties][name] = property
-            # Primitives support
+            property[:format] = PARAM_TYPES[field.type][:format] if PARAM_TYPES[field.type][:format]
+
             if PRIMITIVES.include? field.attributes
-              property[:items] =
-                { type: field.attributes.to_s.split('_').last.to_sym }
+              property[:items] = { type: field.attributes }
+            elsif field.type == :object && field.attributes.is_a?(Symbol)
+              property = { '$ref' => "#/components/schemas/#{field.attributes}" }
+            elsif field.type == :array && field.attributes.is_a?(Symbol)
+              property = { type: :array, items: { '$ref' => "#/components/schemas/#{field.attributes}" } }
             end
+
             required.push name unless field.required == false
+
+            schema[:properties][name] = property
           end
 
           schema[:required] = required unless required.size.zero?
@@ -210,10 +261,10 @@ module RSpec
         #
         #
         # @return [void]
-        def process_path_param(name, param) # rubocop:disable Metrics/MethodLength
+        def process_path_param(name, param) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
           parameter = {
             name:        name.to_s,
-            description: param[:description],
+            description: param[:description].presence&.strip || '',
             required:    param[:required] || true,
             in:          param[:scope].to_s,
             schema:      {
@@ -239,7 +290,7 @@ module RSpec
         #
         # FIXME: Rename "action_config" to "action"
         # FIXME: Rename "parameters" to "path_parameters"
-        # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
         def process_action(resource: nil, path: nil, path_config: nil, action_config: nil, parameters: nil)
           responses    = {}
           request_body = nil
@@ -257,21 +308,31 @@ module RSpec
             responses[status_key] = process_response status: status_key, status_config: status, content: content
           end
 
-          summary = path_config[:actions][action_config][:summary]
-          action  = {
-            summary:     summary,
-            description: path_config[:actions][action_config][:description],
-            operationId: "#{resource} #{summary}".downcase.gsub(/[^\w]/, '_'),
+          action = {
+            summary:     path_config[:actions][action_config][:summary]&.strip || '',
+            description: path_config[:actions][action_config][:description].presence&.strip || '',
+            operationId: "#{resource} #{action_config} #{path}".downcase.gsub(/[^\w]/, '_'),
             parameters:  parameters,
             responses:   responses,
             tags:        [resource.to_s],
           }
 
+          if path_config[:actions][action_config].key? :security
+            references = path_config[:actions][action_config][:security]
+
+            action[:security] = []
+            references.each do |reference|
+              raise "No security scheme defined with reference #{reference}" unless @api_security.key? reference
+
+              action[:security].push({ reference => [] })
+            end
+          end
+
           action[:requestBody] = request_body if request_body
 
           action
         end
-        # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+        # rubocop:enable Metrics/AbcSize, Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
         ##
         # Processes a request body from metadata
@@ -282,12 +343,13 @@ module RSpec
         #
         # @return [void]
         def process_request_body(schema: nil, ref: nil, examples: {})
-          Utils.deep_set @api_components, "schemas.#{ref}", schema
+          Utils.deep_set @api_components, ['schemas', ref], schema
+
           {
             # description: '',
             required: true,
             content:  {
-              'application/json' => {
+              content_type_from_schema(schema) => {
                 schema:   { '$ref' => "#/components/schemas/#{ref}" },
                 examples: examples,
               },
@@ -295,6 +357,23 @@ module RSpec
           }
         end
 
+        def content_type_from_schema(schema)
+          schema_includes_file?(schema) ? 'multipart/form-data' : 'application/json'
+        end
+
+        def schema_includes_file?(schema)
+          return true if schema[:type] == 'string' && schema[:format] == 'binary'
+          return false unless schema[:properties].is_a?(Hash) && schema[:required].is_a?(Array)
+
+          schema[:properties].each_value do |definition|
+            next unless schema_includes_file?(definition)
+
+            return true
+          end
+
+          false
+        end
+
         ##
         # Process a response from metadata
         #
@@ -303,31 +382,58 @@ module RSpec
         # @param content       [String] Response content
         #
         # @return [void]
-        def process_response(status: nil, status_config: nil, content: nil)
-          response = { description: status_config[:description] }
+        def process_response(status: nil, status_config: nil, content: nil) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+          response = { description: status_config[:description].presence&.strip || '' }
 
           return response if status.to_s == '204' && content # No content
 
+          data = begin
+            JSON.parse(content)
+          rescue JSON::ParserError, TypeError
+            content
+          end
+
+          entity = status_config[:expectations][:one] || status_config[:expectations][:many]
+
+          # TODO: handle sub-entities
+          if @redactables.key?(entity) && data.is_a?(Hash)
+            if status_config[:expectations][:one]
+              @redactables[entity].each_pair do |attribute, replacement|
+                data[attribute.to_s] = replacement
+              end
+            else
+              data.each_index do |index|
+                @redactables[entity].each_pair do |attribute, replacement|
+                  data[index][attribute.to_s] = replacement
+                end
+              end
+            end
+          end
+
           response[:content] = {
             'application/json': {
               schema:   response_schema(status_config[:expectations]),
-              examples: { default: { value: JSON.parse(content) } },
+              examples: { default: { value: data } },
             },
           }
 
           response
         end
 
-        def response_schema(expectations)
+        def response_schema(expectations) # rubocop:disable Metrics/MethodLength
           if expectations[:many]
             items = if PRIMITIVES.include?(expectations[:many])
-                      { type: expectations[:many].to_s.split('_').last }
+                      { type: expectations[:many] }
                     else
                       { '$ref' => "#/components/schemas/#{expectations[:many]}" }
                     end
             { type: 'array', items: items }
           elsif expectations[:one]
-            { '$ref' => "#/components/schemas/#{expectations[:one]}" }
+            if PRIMITIVES.include?(expectations[:one])
+              { type: expectations[:one] }
+            else
+              { '$ref' => "#/components/schemas/#{expectations[:one]}" }
+            end
           end
         end
 
@@ -350,6 +456,16 @@ module RSpec
           request_examples
         end
 
+        def global_entities
+          return if RSpec::Rails::Api::Metadata.entities.keys.count.zero?
+
+          @api_components[:schemas] = {}
+
+          RSpec::Rails::Api::Metadata.entities.each_pair do |name, entity|
+            @api_components[:schemas][name] = process_entity(entity)
+          end
+        end
+
         ##
         # Converts path with params like ":id" to their OpenAPI representation
         #
@@ -376,12 +492,12 @@ module RSpec
         # Fills the API general information sections
         #
         # @return [void]
-        def api_infos
+        def api_infos # rubocop:disable Metrics/CyclomaticComplexity
           @api_infos = {
             title:   @api_title || 'Some sample app',
             version: @api_version || '1.0',
           }
-          @api_infos[:description]    = @api_description if @api_description
+          @api_infos[:description]    = @api_description.strip || '' if @api_description.present?
           @api_infos[:termsOfService] = @api_tos if @api_tos
           @api_infos[:contact]        = @api_contact if @api_contact[:name]
           @api_infos[:license]        = @api_license if @api_license[:name]

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

@@ -7,139 +7,38 @@ module RSpec
     module Api
       # Helper methods
       class Utils
-        ##
-        # Gets a value in a hash by specifying a dotted path
-        #
-        # @param hash [Hash]   The hash to search in
-        # @param path [String] The dotted path
-        #
-        # @return [*] The value or nil
-        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] # rubocop:disable Lint/UnmodifiedReduceAccumulator
+        class << self
+          ##
+          # Sets a value at given dotted path in a hash
+          #
+          # @param hash      [Hash]   The target hash
+          # @param path      [Array]  List of keys to access value
+          # @param value     [*]      Value to set
+          #
+          # @return [Hash] The modified hash
+          def deep_set(hash, path, value)
+            raise 'path should be an array' unless path.is_a? Array
+
+            return value if path.count.zero?
+
+            current_key       = path.shift.to_s.to_sym
+            hash[current_key] = {} unless hash[current_key].is_a?(Hash)
+            hash[current_key] = deep_set(hash[current_key], path, value)
+
+            hash
           end
-        end
-
-        ##
-        # Sets a value at given dotted path in a hash
-        #
-        # @param hash  [Hash]   The target hash
-        # @param path  [String] Dotted path
-        # @param value [*]      Value to set
-        #
-        # @return [Hash] The modified hash
-        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
-
-        ##
-        # Checks if a value is of the given parameter type
-        #
-        # @param type  [Symbol] Type to compare to
-        # @param value [*]      Value to test
-        #
-        # @return [Boolean] True when the value corresponds to the given type
-        def self.check_value_type(type, value)
-          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
-
-        ##
-        # Validates an object keys and values types
-        #
-        # @param actual   [Hash] Hash to compare
-        # @param expected [Hash] Structure to compare
-        #
-        # @return [Boolean] True when the object matches the structure
-        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]
+          ##
+          # Returns a hash from an object
+          #
+          # @param value [Hash,Class] A hash or something with a "body" (as responses object in tests)
+          #
+          # @return [Hash]
+          def hash_from_response(value)
+            return JSON.parse(value.body) if value.respond_to? :body
 
-            # Deep object ?
-            return false unless validate_deep_object expected_type, expected_attributes, actual[key.to_s]
+            value
           end
-
-          true
-        end
-
-        ##
-        # Validates an array or hash against a definition
-        #
-        # @param expected_type       [:object, :array] The expected type
-        # @param expected_attributes [Hash]            Attributes configuration
-        # @param actual              [Array, Hash]     Value to check
-        #
-        # @return [Boolean] True when `actual` is of the expected definition
-        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
-              return false unless validate_deep_object_array actual, expected_attributes
-            end
-          end
-
-          true
-        end
-
-        ##
-        # Validates each entry of an array
-        #
-        # @param array               [Array] The array to check
-        # @param expected_attributes [Hash]  Attributes configuration
-        #
-        # @return [Boolean] True when all values matches the attribute configuration
-        def self.validate_deep_object_array(array, expected_attributes)
-          array.each do |array_entry|
-            if expected_attributes[:type]
-              return false unless check_value_type expected_attributes[:type], array_entry
-            else
-              return false unless validate_object_structure array_entry, expected_attributes
-            end
-          end
-
-          true
-        end
-
-        ##
-        # Checks if a hash have the required keys in it
-        #
-        # @param actual   [Hash] The hash
-        # @param expected [Hash] Attributes definitions
-        #
-        # @return [Boolean] True when the object is valid
-        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