rspec-rails-api 0.3.4 → 0.5.0

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

@@ -1,15 +1,16 @@
 # frozen_string_literal: true
 
 require 'rspec/rails/api/utils'
+require 'rspec/rails/api/validator'
 require 'rspec/rails/api/open_api_renderer'
 require 'rspec/rails/api/entity_config'
 
 module RSpec
   module Rails
     module Api
-      # Handles contexts and examples metadatas.
+      # Handles contexts and examples metadata.
       class Metadata # rubocop:disable Metrics/ClassLength
-        attr_reader :entities, :resources, :current_resource, :parameters
+        attr_reader :entities, :resources, :parameters, :current_resource, :current_url, :current_method, :current_code
 
         def initialize
           @resources  = {}
@@ -22,37 +23,65 @@ module RSpec
           @current_code     = nil
         end
 
+        ##
+        # Adds a resource to metadata
+        #
+        # @param name        [String] Resource name
+        # @param description [String] Resource description
+        #
+        # @return [void]
         def add_resource(name, description)
-          @resources[name.to_sym] = { description: description, paths: {} }
+          @resources[name.to_sym] = { description: description, paths: {}, entities: {} }
           @current_resource       = name.to_sym
         end
 
-        def add_entity(type, fields)
+        ##
+        # Adds an entity definition
+        #
+        # @param name   [Symbol] Entity name
+        # @param fields [Hash]   Fields definitions
+        #
+        #
+        # @return [void]
+        def add_entity(name, fields)
           Utils.deep_set(@resources,
-                         "#{@current_resource}.entities.#{type}",
+                         [@current_resource, 'entities', name],
                          EntityConfig.new(fields))
         end
 
-        def add_parameter(type, fields)
-          raise "Parameter #{type} is already defined" if @parameters[type]
+        ##
+        # Adds a parameter definition
+        #
+        # @param name   [Symbol] Parameter definition name
+        # @param fields [Hash]   Fields definitions
+        #
+        # @return [void]
+        def add_parameter(name, fields)
+          raise "Parameter #{name} is already defined" if @parameters[name]
 
           fields.each_value do |field|
             field[:required] = true unless field[:required] == false
           end
-          @parameters[type] = fields
+          @parameters[name] = fields
         end
 
+        ##
+        # Adds path parameters definition
+        #
+        # @param fields [Hash] Parameters definitions
+        #
+        # @return [void]
         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])
+            valid_attribute = Validator.valid_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}",
+            Utils.deep_set(@resources, [@current_resource, 'paths', @current_url, 'path_params', name],
                            description: field[:description] || nil,
                            type:        field[:type] || nil,
                            required:    field[:required] || true,
@@ -60,6 +89,9 @@ module RSpec
           end
         end
 
+        ##
+        # Add request parameters (_body_)
+        #
         # Fields should be something like:
         #   id:   {type: :number, description: 'Something'},
         #   name: {type: string, description: 'Something'}
@@ -69,20 +101,34 @@ module RSpec
         #     property: {type: :string, description: 'Something'},
         #     ...
         #   }}
+        #
+        # @param fields [Hash] Parameters definitions
+        #
+        # @return [void]
         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",
+                         [@current_resource, 'paths', @current_url, 'actions', @current_method, 'params'],
                          params)
         end
 
-        def add_action(method, url, description)
+        ##
+        # Adds an action and sets `@current_url` and `@current_method`
+        #
+        # @param method      [:get, :post, :put, :patch, delete] Method name
+        # @param url         [String]                            Associated URL
+        # @param summary     [String]                            What the route does for given method
+        # @param description [String]                            Longer description of this action
+        #
+        # @return [void]
+        def add_action(method, url, summary, description = '')
           check_current_context :resource
 
-          Utils.deep_set(@resources, "#{@current_resource}.paths.#{url}.actions.#{method}",
-                         description: description,
+          Utils.deep_set(@resources, [@current_resource, 'paths', url, 'actions', method],
+                         description: description || '',
+                         summary:     summary,
                          statuses:    {},
                          params:      {})
 
@@ -90,35 +136,91 @@ module RSpec
           @current_method = method
         end
 
+        ##
+        # Adds a status code to metadata and sets `@current_code`
+        #
+        # @param status_code [Integer] The status code
+        # @param description [String]  Code description
+        #
+        # @return [void]
+        #
         # rubocop:disable Layout/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}",
+                         [@current_resource, 'paths', @current_url, 'actions', @current_method, 'statuses', status_code],
                          description: description,
                          example:     { response: nil })
           @current_code = status_code
         end
         # rubocop:enable Layout/LineLength
 
+        ##
+        # Gets the current example
+        #
+        # @return [Hash] Current example metadata
+        def current_example
+          @resources.dig @current_resource,
+                         :paths,
+                         @current_url.to_sym,
+                         :actions,
+                         @current_method.to_sym,
+                         :statuses,
+                         @current_code.to_s.to_sym
+        end
+
+        ##
+        # Adds expectations for current example
+        #
+        # @param one [Hash, nil] Entity definition
+        # @param many [Hash, nil] Entity definition
+        #
+        # @return [void]
+        def add_expectations(one, many)
+          check_current_context :resource, :url, :method, :code
+          none = !many && !one
+
+          # rubocop:disable Layout/LineLength
+          Utils.deep_set(@resources,
+                         [@current_resource, 'paths', @current_url, 'actions', @current_method, 'statuses', @current_code, 'expectations'],
+                         {
+                           one:  one,
+                           many: many,
+                           none: none,
+                         })
+          # rubocop:enable Layout/LineLength
+        end
+
+        ##
+        # Adds a request example
+        #
+        # @param url         [String, nil]  Visited URL
+        # @param action      [String, nil]  HTTP verb
+        # @param status_code [Integer, nil] Status code
+        # @param response    [String, nil]  Response body
+        # @param path_params [Hash, nil]    Used path parameters
+        # @param params      [Hash, nil]    Used body parameters
+        #
         # 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}")
+            resource = key if res.dig :paths, url.to_sym, :actions, action.to_sym, :statuses, status_code.to_s.to_sym
           end
 
           raise "Resource not found for #{action.upcase} #{url}" unless resource
 
           Utils.deep_set(@resources,
-                         "#{resource}.paths.#{url}.actions.#{action}.statuses.#{status_code}.example",
+                         [resource, 'paths', url, 'actions', action, 'statuses', status_code, 'example'],
                          path_params: path_params,
                          params:      params,
                          response:    response)
         end
         # rubocop:enable Metrics/ParameterLists
 
+        ##
+        # @return [Hash] Hash representation of the metadata
         def to_h
           {
             resources: @resources,
@@ -128,6 +230,13 @@ module RSpec
 
         private
 
+        ##
+        # Checks for the definition of given scopes.
+        # This is useful to verify if all metadata is set for the current example
+        #
+        # @param scope [Symbol[]] List of scope to check for
+        #
+        # @return [Boolean]
         def check_current_context(*scope) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
           scope ||= []
           raise 'No resource declared' if scope.include?(:resource) && !@current_resource
@@ -136,6 +245,13 @@ module RSpec
           raise 'No status code declared' if scope.include?(:code) && !@current_code
         end
 
+        ##
+        # Checks if a given parameter is used in the URL (_path_) or querystring (query)
+        #
+        # @param url_chunks [String[]] Chunks of an url splitted on the query separator (`?`)
+        # @param name       [Symbol]   Name of the parameter
+        #
+        # @return [:path, :query]
         def path_param_scope(url_chunks, name)
           if /:#{name}/.match?(url_chunks[0])
             :path
@@ -146,15 +262,25 @@ module RSpec
           end
         end
 
-        def organize_params(fields) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        ##
+        # Checks and complete a field definition
+        #
+        # @param fields [Hash,Symbol] Fields definitions
+        #
+        # @return [Hash,Symbol] Completed field definition
+        def organize_params(fields) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+          return fields if fields.is_a?(Symbol) && PRIMITIVES.include?(fields)
+          raise "Unsupported type \"#{fields}\"" unless fields.is_a? Hash
+
           out      = { properties: {} }
           required = []
+
           allowed_types = %i[array object]
           fields.each do |name, field|
             allowed_type = allowed_types.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]
+            required.push name.to_s if field[:required] != false
 
             out[:properties][name] = fill_request_param field
           end
@@ -162,9 +288,15 @@ module RSpec
           out
         end
 
+        ##
+        # Checks and completes a request parameter definition
+        #
+        # @param field [Hash] Parameter definition
+        #
+        # @return [Hash] Completed parameter
         def fill_request_param(field)
-          if field[:type] == :object && field[:properties]
-            organize_params field[:properties]
+          if field[:type] == :object && field[:attributes]
+            organize_params field[:attributes]
           else
             properties = {
               type:        PARAM_TYPES[field[:type]][:type],

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
@@ -27,46 +27,80 @@ module RSpec
           @api_license    = {}
         end
 
+        ##
+        # Merges example context definition with the renderer data
+        #
+        # @param context       [Hash]    Metadata hash
+        # @param dump_metadata [Boolean] Saves the raw metadata in `tmp/rra_metadata.yaml` for debugging
+        #
+        # @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]
+          @metadata[:entities].deep_merge! context.respond_to?(:entities) ? context.entities : context[:entities]
 
           # 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
 
+        ##
+        # Write OpenAPI files
+        #
+        # @param path [String, nil] Where to save the files. Defaults to `/tmp/rspec_api_rails.*` when unset
+        # @param only [[Symbol]]    Formats to save the file to. Allowed values are `:yaml` and `:json`
+        #
+        # @return [void]
         def write_files(path = nil, only: %i[yaml json])
-          content = prepare_metadata
+          return unless write_file? RSpec.world.filtered_examples
+
           path ||= ::Rails.root.join('tmp', 'rspec_api_rails')
 
           file_types = %i[yaml json]
-
           only.each do |type|
             next unless file_types.include? type
 
-            File.write "#{path}.#{type}", JSON.parse(JSON.pretty_generate(content)).send("to_#{type}")
+            File.write "#{path}.#{type}", prepare_metadata.send("to_#{type}")
           end
         end
 
+        ##
+        # Extracts metadata from context to generate an OpenAPI structure
+        #
+        # @return [Hash] The OpenAPI structure
         def prepare_metadata
+          extract_metadata
           # Example: https://github.com/OAI/OpenAPI-Specification/blob/master/examples/v3.0/petstore-expanded.yaml
-          extract_metadatas
-          {
+          hash = {
             openapi:    '3.0.0',
             info:       @api_infos,
             servers:    @api_servers,
             paths:      @api_paths,
             components: @api_components,
             tags:       @api_tags,
-          }.deep_stringify_keys
+          }
+          JSON.parse(JSON.pretty_generate(hash))
         end
 
+        ##
+        # Sets the contact field
+        #
+        # @param name  [String, nil] Contact name
+        # @param email [String, nil] Contact Email
+        # @param url   [String, nil] Contact URL
+        #
+        # @return [void]
         def api_contact=(name: nil, email: nil, url: nil)
           @api_contact[:name]  = name if name
           @api_contact[:email] = email if email
           @api_contact[:url]   = url if url
         end
 
+        ##
+        # Sets the license field
+        #
+        # @param name  [String, nil] License name
+        # @param url   [String, nil] License URL
+        #
+        # @return [void]
         def api_license=(name: nil, url: nil)
           @api_license[:name] = name if name
           @api_license[:url] = url if url
@@ -74,14 +108,38 @@ module RSpec
 
         private
 
-        def extract_metadatas
+        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_metadata
           extract_from_resources
           api_infos
           api_servers
         end
 
-        def extract_from_resources
+        ##
+        # Extracts metadata from resources for rendering
+        #
+        # @return [void]
+        def extract_from_resources # rubocop:disable Metrics/MethodLength
+          @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]
@@ -90,6 +148,14 @@ module RSpec
           end
         end
 
+        ##
+        # Processes a resource from metadata
+        #
+        # @param resource        [Symbol, nil] Resource name
+        # @param resource_config [Hash, nil]   Resource declaration
+        #
+        #
+        # @return [void]
         def process_resource(resource: nil, resource_config: nil) # rubocop:disable Metrics/MethodLength
           http_verbs = %i[get post put patch delete]
           resource_config[:paths].each do |path_key, path|
@@ -111,6 +177,10 @@ module RSpec
           end
         end
 
+        ##
+        # Processes path parameters for rendering
+        #
+        # @param params [Hash] Path parameters
         def process_path_params(params)
           parameters = []
           params.each do |name, param|
@@ -120,6 +190,37 @@ module RSpec
           parameters
         end
 
+        def process_entity(entity) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+          schema = {
+            properties: {},
+          }
+          required = []
+          entity.fields.each do |name, field|
+            property = {
+              description: field.description,
+              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[:items] = { type: field.attributes } if PRIMITIVES.include? field.attributes
+
+            required.push name unless field.required == false
+          end
+
+          schema[:required] = required unless required.size.zero?
+
+          schema
+        end
+
+        ##
+        # Processes a path parameter from metadata
+        #
+        # @param name  [Symbol, nil] Parameter name
+        # @param param [Hash, nil]   Parameter declaration
+        #
+        #
+        # @return [void]
         def process_path_param(name, param) # rubocop:disable Metrics/MethodLength
           parameter = {
             name:        name.to_s,
@@ -136,6 +237,19 @@ module RSpec
           parameter
         end
 
+        ##
+        # Processes an action from metadata
+        #
+        # @param resource      [Symbol, nil] Target resource
+        # @param path          [Symbol, nil] Target path
+        # @param path_config   [Hash, nil]   Path configuraton
+        # @param action_config [Symbol, nil] Target action
+        # @param parameters    [Array, nil]  Path parameters
+        #
+        # @return [void]
+        #
+        # FIXME: Rename "action_config" to "action"
+        # FIXME: Rename "parameters" to "path_parameters"
         # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
         def process_action(resource: nil, path: nil, path_config: nil, action_config: nil, parameters: nil)
           responses    = {}
@@ -154,10 +268,11 @@ module RSpec
             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]/, '_'),
+          summary = path_config[:actions][action_config][:summary]
+          action  = {
+            summary:     summary,
+            description: path_config[:actions][action_config][:description],
+            operationId: "#{resource} #{summary}".downcase.gsub(/[^\w]/, '_'),
             parameters:  parameters,
             responses:   responses,
             tags:        [resource.to_s],
@@ -169,8 +284,16 @@ module RSpec
         end
         # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
 
+        ##
+        # Processes a request body from metadata
+        #
+        # @param schema   [Hash]   Schema
+        # @param ref      [String] Reference
+        # @param examples [Hash]   Example
+        #
+        # @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,
@@ -183,15 +306,22 @@ module RSpec
           }
         end
 
+        ##
+        # Process a response from metadata
+        #
+        # @param status        [Symbol] Status code
+        # @param status_config [Hash]   Configuration for status code
+        # @param content       [String] Response content
+        #
+        # @return [void]
         def process_response(status: nil, status_config: nil, content: nil)
-          response = {
-            description: status_config[:description],
-          }
+          response = { description: status_config[:description] }
 
           return response if status.to_s == '204' && content # No content
 
           response[:content] = {
             'application/json': {
+              schema:   response_schema(status_config[:expectations]),
               examples: { default: { value: JSON.parse(content) } },
             },
           }
@@ -199,6 +329,25 @@ module RSpec
           response
         end
 
+        def response_schema(expectations)
+          if expectations[:many]
+            items = if PRIMITIVES.include?(expectations[:many])
+                      { type: expectations[:many] }
+                    else
+                      { '$ref' => "#/components/schemas/#{expectations[:many]}" }
+                    end
+            { type: 'array', items: items }
+          elsif expectations[:one]
+            { '$ref' => "#/components/schemas/#{expectations[:one]}" }
+          end
+        end
+
+        ##
+        # Processes examples from statuses
+        #
+        # @param statuses [Hash]
+        #
+        # @return [Hash] Request examples
         def process_examples(statuses)
           request_examples = {}
 
@@ -212,16 +361,32 @@ module RSpec
           request_examples
         end
 
+        ##
+        # Converts path with params like ":id" to their OpenAPI representation
+        #
+        # @param string [String] The original path
+        #
+        # @return [String] OpenAPI path representation
         def path_with_params(string)
           string.gsub(/(?::(\w*))/) do |e|
             "{#{e.sub(':', '')}}"
           end
         end
 
+        ##
+        # Converts a string to a snake_cased string to use as operationId
+        #
+        # @param string [String] Original string
+        #
+        # @return [String] Snake_cased string
         def escape_operation_id(string)
           string.downcase.gsub(/[^\w]+/, '_')
         end
 
+        ##
+        # Fills the API general information sections
+        #
+        # @return [void]
         def api_infos
           @api_infos = {
             title:   @api_title || 'Some sample app',
@@ -235,6 +400,10 @@ module RSpec
           @api_infos
         end
 
+        ##
+        # Fills the API servers section
+        #
+        # @return [void]
         def api_servers
           @api_servers || [
             { url: 'http://api.example.com' },