rspec-rails-api 0.3.4 → 0.4.0

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

@@ -27,6 +27,13 @@ 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]
@@ -35,8 +42,14 @@ module RSpec
           File.write ::Rails.root.join('tmp', 'rra_metadata.yaml'), context.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
           path ||= ::Rails.root.join('tmp', 'rspec_api_rails')
 
           file_types = %i[yaml json]
@@ -44,29 +57,49 @@ module RSpec
           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
-          # Example: https://github.com/OAI/OpenAPI-Specification/blob/master/examples/v3.0/petstore-expanded.yaml
           extract_metadatas
-          {
+          # Example: https://github.com/OAI/OpenAPI-Specification/blob/master/examples/v3.0/petstore-expanded.yaml
+          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 +107,26 @@ module RSpec
 
         private
 
+        ##
+        # Extracts metadata for rendering
+        #
+        # @return [void]
         def extract_metadatas
           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 +135,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 +164,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 +177,39 @@ 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
+            if PRIMITIVES.include? field.attributes
+              property[:items] =
+                { type: field.attributes.to_s.split('_').last.to_sym }
+            end
+            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 +226,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 +257,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,6 +273,14 @@ 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
           {
@@ -183,15 +295,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 +318,25 @@ module RSpec
           response
         end
 
+        def response_schema(expectations)
+          if expectations[:many]
+            items = if PRIMITIVES.include?(expectations[:many])
+                      { type: expectations[:many].to_s.split('_').last }
+                    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 +350,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 +389,10 @@ module RSpec
           @api_infos
         end
 
+        ##
+        # Fills the API servers section
+        #
+        # @return [void]
         def api_servers
           @api_servers || [
             { url: 'http://api.example.com' },

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

@@ -7,6 +7,13 @@ 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)
@@ -15,6 +22,14 @@ module RSpec
           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
 
@@ -27,6 +42,13 @@ module RSpec
           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)
@@ -36,6 +58,13 @@ module RSpec
           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
@@ -56,23 +85,53 @@ module RSpec
           true
         end
 
-        # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength
+        ##
+        # 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
-              actual.each do |array_entry|
-                return false unless validate_object_structure array_entry, expected_attributes
-              end
+              return false unless validate_deep_object_array actual, expected_attributes
             end
           end
 
           true
         end
-        # rubocop:enable Metrics/CyclomaticComplexity, Metrics/MethodLength
 
+        ##
+        # 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

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

@@ -3,7 +3,7 @@
 module RSpec
   module Rails
     module Api
-      VERSION = '0.3.4'
+      VERSION = '0.4.0'
     end
   end
 end

data/lib/rspec_rails_api.rb

@@ -15,6 +15,8 @@ module RSpec
       class Error < StandardError
       end
 
+      ##
+      # OpenAPI types, format and Ruby class correspondence
       PARAM_TYPES = {
         int32:    { type: 'integer', format: 'int32', class: Integer },
         int64:    { type: 'integer', format: 'int64', class: Integer },
@@ -32,6 +34,12 @@ module RSpec
         array:    { type: 'array', format: nil, class: Array },
         object:   { type: 'object', format: nil, class: Hash },
       }.freeze
+
+      EXCLUDED_PRIMITIVES = %i[array object].freeze
+
+      PRIMITIVES = PARAM_TYPES.keys
+                              .reject { |key| EXCLUDED_PRIMITIVES.include? key }
+                              .map { |key| "type_#{key}".to_sym }
     end
   end
 end

data/rspec-rails-api.gemspec

@@ -18,9 +18,10 @@ Gem::Specification.new do |spec|
   spec.homepage = 'https://gitlab.com/experimentslabs/rspec-rails-api'
   spec.license  = 'MIT'
   spec.metadata = {
-    'source_code_uri' => 'https://gitlab.com/experimentslabs/rspec-rails-api',
-    'bug_tracker_uri' => 'https://gitlab.com/experimentslabs/rspec-rails-api/issues',
-    'changelog_uri'   => 'https://gitlab.com/experimentslabs/rspec-rails-api/blob/master/CHANGELOG.md',
+    'source_code_uri'       => 'https://gitlab.com/experimentslabs/rspec-rails-api',
+    'bug_tracker_uri'       => 'https://gitlab.com/experimentslabs/rspec-rails-api/issues',
+    'changelog_uri'         => 'https://gitlab.com/experimentslabs/rspec-rails-api/blob/master/CHANGELOG.md',
+    'rubygems_mfa_required' => 'true',
   }
 
   # Specify which files should be added to the gem when it is released.
@@ -35,11 +36,12 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = '>= 2.5.0'
 
   spec.add_development_dependency 'activesupport', '~> 6.0'
-  spec.add_development_dependency 'bundler', '~> 1.17'
+  spec.add_development_dependency 'bundler'
   spec.add_development_dependency 'byebug'
   spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_development_dependency 'rspec', '~> 3.0'
   spec.add_development_dependency 'rubocop'
   spec.add_development_dependency 'rubocop-performance'
   spec.add_development_dependency 'simplecov'
+  spec.add_development_dependency 'yard'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rspec-rails-api
 version: !ruby/object:Gem::Version
-  version: 0.3.4
+  version: 0.4.0
 platform: ruby
 authors:
 - Manuel Tancoigne
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-10-20 00:00:00.000000000 Z
+date: 2021-12-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -28,16 +28,16 @@ dependencies:
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.17'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.17'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: byebug
   requirement: !ruby/object:Gem::Requirement
@@ -122,6 +122,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: |
   Create acceptance tests to check the Rails API responses and generate
   documentation from it.
@@ -162,6 +176,7 @@ metadata:
   source_code_uri: https://gitlab.com/experimentslabs/rspec-rails-api
   bug_tracker_uri: https://gitlab.com/experimentslabs/rspec-rails-api/issues
   changelog_uri: https://gitlab.com/experimentslabs/rspec-rails-api/blob/master/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 post_install_message: 
 rdoc_options: []
 require_paths: