rspec-rails-api 0.2.2 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: df99a2088657641a87ec55c6159cdf7973d75863718f94aebef6cc70d7b4ac95
-  data.tar.gz: 4bf341e1fc70d6dfe760a531e43aec6c4c8002b3c1000fe83d1b2ae3cac3f3a0
+  metadata.gz: 8c254dadb291d2de68f549efc3c26407a9bf67b23058d495af7543534ee6b5dd
+  data.tar.gz: f67dedb6a9b0336fade718fd4249781a7db541f22017ae793f6ccc449d7fdd27
 SHA512:
-  metadata.gz: 42b42ba732de1383324dde829463f6a042289f184a959a9dc1c8ff727d8fd56699f7e97f40d215f184f724249517be826f5de4a66a5e684593a166ee25843624
-  data.tar.gz: 2daa6738912fcf4192e7c155a6744400420cabb5b1422de6dca77d34ece4dee59528d228b85af52fed0e5eaa17aebb4d14b06ca46e913a81c46318c8b11b67da
+  metadata.gz: 988cdf3140fa6de3fe5f290ba43114a52e9037e158b8d6acec65c850d86cf4563b7c5870b2137424ffaeaaf887d4c368f1bfacc448363ee31984e17de6594b95
+  data.tar.gz: 81945d8559b1b1ff3bcd0de08542eead1ad1b30c3fd8d9472cd89ac128e22afa1b385abed2e54daf636c19bb220224842c0e1dc560aa9959f6256f11545505b7

data/.gitlab-ci.yml

@@ -1,5 +1,5 @@
 ---
-image: ruby:2.4
+image: ruby:2.5
 
 stages:
   - prepare

data/.rubocop.yml

@@ -3,25 +3,27 @@ require:
   - rubocop-performance
 
 AllCops:
+  TargetRubyVersion: 2.5
   Exclude:
     - dummy/**/*
     - vendor/bundle/**/*
+  NewCops: enable
 
-Metrics/BlockLength:
+Layout/LineLength:
+  Max: 120
   Exclude:
-    - rspec-rails-api.gemspec
     - spec/**/*_spec.rb
 
-Metrics/LineLength:
-  Max: 120
+Metrics/BlockLength:
   Exclude:
+    - rspec-rails-api.gemspec
     - spec/**/*_spec.rb
 
-Naming/UncommunicativeMethodParamName:
+Naming/MethodParameterName:
   AllowedNames:
     - of
 
-Layout/AlignHash:
+Layout/HashAlignment:
   EnforcedColonStyle: table
   EnforcedHashRocketStyle: table
 

data/CHANGELOG.md

@@ -3,6 +3,26 @@ All notable changes to this project will be documented in this file.
 
 ## Not released
 
+## 0.3.2 - 2021-03-09
+- Fix YAML rendering (ruby objects were sometimes rendered in documentation)
+- Render examples results as YAML/JSON objects instead of text blocks.
+
+## 0.3.1 - 2020-04-09
+- Add support for "test only" examples, allowing to write examples without documentation.
+
+## 0.3.0 - 2019-12-26
+
+### Changed
+- Rails 6 support, deprecated methods from Rails 5 are not supported. Use version `0.2.3` 
+  of this gem if your application is still on 5.
+
+## 0.2.3 - 2019-12-04
+
+### Improved
+
+- Generated Swagger file now use the payloads of POST/PATCH/PUT requests.
+- Minimum Ruby version is now specified: Ruby 2.3.3.
+
 ## 0.2.1/0.2.2 - 2019-11-03
 
 _Version 0.2.1 was released and yanked by mistake. Version 0.2.2 is the exact

data/README.md

@@ -6,6 +6,8 @@
 **This is a work in progress** but you're welcome to help, test, submit
 issues, ...
 
+**Note** For Rails 5, use version 0.2.3
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -378,7 +380,7 @@ on_post '/api/items' do
 end
 ```
 
-##### `for_code(http_status, description = nil, doc_only: false &block)`
+##### `for_code(http_status, description = nil, doc_only: false, test_only: false &block)`
 
 Describes the desired output for a precedently defined URL.
 
@@ -386,6 +388,9 @@ Block takes one required argument, that should be passed to `visit`.
 This argument will contain the block context and allow `visit` to access
 the metadatas.
 
+You can have only one documented code per action/url, unless you use
+`test_only`.
+
 - `http_status` is an integer representing an
   [HTTP status](https://httpstat.us/)
 - `description` should be some valid
@@ -393,6 +398,8 @@ the metadatas.
   translation of the `http_status` will be used.
 - `doc_only` can be set to true to temporarily disable block execution
   and only create the documentation (without examples).
+- `test_only` will omit the test from the documentation. Useful when you
+  need to test things _around_ the call (response content, db,...)
 - `block` where additional tests can be performed. If `visit()` is
   called within the block, its output will be used in documentation
   examples, and the response type and code will actually be tested.
@@ -410,6 +417,11 @@ Once again, you have to pass an argument to the block if you use
     visit url
     # ...
   end
+  
+  for_code 200, 'Side test', test_only: true do |url|
+    visit url
+    # ...
+  end
 # ...
 ```
 

data/lib/rspec/rails/api/dsl/example.rb

@@ -6,11 +6,13 @@ module RSpec
       module DSL
         # These methods will be available in examples (i.e.: 'for_code')
         module Example
-          def visit(example, path_params: {}, payload: {}, headers: {}) # rubocop:disable Metrics/AbcSize
+          def visit(example, path_params: {}, payload: {}, headers: {}) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
             raise 'Missing context. Call visit with for_code context.' unless example
 
-            status_code    = prepare_status_code example.class.description
-            request_params = prepare_request_params example.class.parent.description, path_params, payload, headers
+            status_code = prepare_status_code example.class.description
+
+            request_params = prepare_request_params example.class.module_parent.description,
+                                                    path_params, payload, headers
 
             send(request_params[:action],
                  request_params[:url],
@@ -19,6 +21,8 @@ module RSpec
 
             check_response(response, status_code)
 
+            return if example.class.description.match?(/-> test (\d+)(.*)/)
+
             set_request_example example.class.metadata[:rrad], request_params, status_code, response.body
           end
 
@@ -51,7 +55,7 @@ module RSpec
           end
 
           def prepare_request_params(description, request_params = {}, payload = {}, request_headers = {})
-            example_params = description.split ' '
+            example_params = description.split
 
             {
               action:      example_params[0].downcase,
@@ -84,7 +88,7 @@ module RSpec
           end
 
           def prepare_status_code(description)
-            code_match = /-> (\d+) - .*/.match description
+            code_match = /->(?: test)? (\d+) - .*/.match description
 
             raise 'Please provide a numerical code for the "for_code" block' unless code_match
 

data/lib/rspec/rails/api/dsl/example_group.rb

@@ -74,12 +74,12 @@ module RSpec
             describe("#{action.upcase} #{url}", &block)
           end
 
-          def for_code(status_code, description = nil, doc_only: false, &block)
+          def for_code(status_code, description = nil, doc_only: false, test_only: false, &block)
             description ||= Rack::Utils::HTTP_STATUS_CODES[status_code]
 
-            metadata[:rrad].add_status_code(status_code, description)
+            metadata[:rrad].add_status_code(status_code, description) unless test_only
 
-            describe "-> #{status_code} - #{description}" do
+            describe "->#{test_only ? ' test' : ''} #{status_code} - #{description}" do
               execute_for_code_block(status_code, doc_only, block)
             end
           end
@@ -89,7 +89,7 @@ module RSpec
           def document_only(status_code)
             example 'Create documentation' do |example|
               parent_example = example.example_group
-              request_params = prepare_request_params parent_example.parent.description
+              request_params = prepare_request_params parent_example.module_parent.description
 
               set_request_example parent_example.metadata[:rrad], request_params, status_code
             end

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

@@ -11,7 +11,7 @@ module RSpec
       class FieldConfig
         attr_accessor :required, :type, :attributes, :description
 
-        def initialize(type:, required: true, description:, attributes: nil, of: nil)
+        def initialize(type:, description:, required: true, attributes: nil, of: nil)
           @required    = required
           @description = description
           raise "Field type not allowed: '#{type}'" unless Utils.check_attribute_type(type)
@@ -40,9 +40,10 @@ module RSpec
         private
 
         def define_attributes(attributes)
-          @attributes = if attributes.is_a? Hash
+          @attributes = case attributes
+                        when Hash
                           @attributes = EntityConfig.new attributes
-                        elsif attributes.is_a? Symbol
+                        when Symbol
                           attributes
                         end
         end

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

@@ -87,7 +87,7 @@ module RSpec
           @current_method = method
         end
 
-        # rubocop:disable Metrics/LineLength
+        # rubocop:disable Layout/LineLength
         def add_status_code(status_code, description)
           check_current_context :resource, :url, :method
 
@@ -97,7 +97,7 @@ module RSpec
                          example:     { response: nil })
           @current_code = status_code
         end
-        # rubocop:enable Metrics/LineLength
+        # rubocop:enable Layout/LineLength
 
         # rubocop:disable Metrics/ParameterLists
         def add_request_example(url: nil, action: nil, status_code: nil, response: nil, path_params: nil, params: nil)
@@ -125,25 +125,14 @@ module RSpec
 
         private
 
-        # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/MethodLength, Style/GuardClause
-        def check_current_context(*scope)
+        def check_current_context(*scope) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
           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
+          raise 'No resource declared' if scope.include?(:resource) && !@current_resource
+          raise 'No action declared' if scope.include?(:method) && !@current_method
+          raise 'No url declared' if scope.include?(:url) && !@current_url
+          raise 'No status code declared' if scope.include?(:code) && !@current_code
         end
 
-        # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/MethodLength, Style/GuardClause
-
         def path_param_scope(url_chunks, name)
           if /:#{name}/.match?(url_chunks[0])
             :path
@@ -154,11 +143,12 @@ module RSpec
           end
         end
 
-        def organize_params(fields) # rubocop:disable Metrics/AbcSize
+        def organize_params(fields) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
           out      = { properties: {} }
           required = []
+          allowed_types = %i[array object]
           fields.each do |name, field|
-            allowed_type = %i[array object].include?(field[:type]) || PARAM_TYPES.key?(field[:type])
+            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]
@@ -174,7 +164,7 @@ module RSpec
             organize_params field[:properties]
           else
             properties = {
-              type:        field[:type].to_s,
+              type:        PARAM_TYPES[field[:type]][:type],
               description: field[:description] || nil,
             }
 

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

@@ -39,10 +39,12 @@ module RSpec
           content = prepare_metadata
           path ||= ::Rails.root.join('tmp', 'rspec_api_rails')
 
+          file_types = %i[yaml json]
+
           only.each do |type|
-            next unless %i[yaml json].include? type
+            next unless file_types.include? type
 
-            File.write "#{path}.#{type}", content.send("to_#{type}")
+            File.write "#{path}.#{type}", JSON.parse(JSON.pretty_generate(content)).send("to_#{type}")
           end
         end
 
@@ -89,13 +91,14 @@ module RSpec
         end
 
         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|
             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
+              next unless http_verbs.include? action
 
               actions[action] = process_action resource:      resource,
                                                path:          path_key,
@@ -117,7 +120,7 @@ module RSpec
           parameters
         end
 
-        def process_path_param(name, param) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+        def process_path_param(name, param) # rubocop:disable Metrics/MethodLength
           parameter = {
             name:        name.to_s,
             description: param[:description],
@@ -138,12 +141,12 @@ module RSpec
           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
+          if %i[post put
+                patch].include?(action_config) && path_config[:actions][action_config][:params].keys.count.positive?
+            schema = path_config[:actions][action_config][:params]
+            schema_ref   = escape_operation_id("#{action_config}_#{path}")
+            examples     = process_examples(path_config[:actions][action_config][:statuses])
+            request_body = process_request_body schema: schema, ref: schema_ref, examples: examples
           end
 
           path_config[:actions][action_config][:statuses].each do |status_key, status|
@@ -166,14 +169,15 @@ module RSpec
         end
         # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
 
-        def process_request_body(schema: nil, ref: nil)
+        def process_request_body(schema: nil, ref: nil, examples: {})
           Utils.deep_set @api_components, "schemas.#{ref}", schema
           {
             # description: '',
             required: true,
             content:  {
               'application/json' => {
-                schema: { '$ref' => "#/components/schemas/#{ref}" },
+                schema:   { '$ref' => "#/components/schemas/#{ref}" },
+                examples: examples,
               },
             },
           }
@@ -184,17 +188,30 @@ module RSpec
             description: status_config[:description],
           }
 
-          return response unless status.to_s != '204' && content # No content
+          return response if status.to_s == '204' && content # No content
 
           response[:content] = {
             'application/json': {
-              examples: { default: { value: JSON.pretty_generate(JSON.parse(content)) } },
+              examples: { default: { value: JSON.parse(content) } },
             },
           }
 
           response
         end
 
+        def process_examples(statuses)
+          request_examples = {}
+
+          statuses.each do |code, request|
+            request_examples[code] = {
+              summary: "Example for a #{code} code",
+              value:   request[:example][:params],
+            }
+          end
+
+          request_examples
+        end
+
         def path_with_params(string)
           string.gsub(/(?::(\w*))/) do |e|
             "{#{e.sub(':', '')}}"
@@ -205,7 +222,7 @@ module RSpec
           string.downcase.gsub(/[^\w]+/, '_')
         end
 
-        def api_infos # rubocop:disable Metrics/CyclomaticComplexity
+        def api_infos
           @api_infos = {
             title:   @api_title || 'Some sample app',
             version: @api_version || '1.0',

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

@@ -11,7 +11,7 @@ module RSpec
           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]
+            sub_hash[key.to_sym] # rubocop:disable Lint/UnmodifiedReduceAccumulator
           end
         end
 
@@ -27,7 +27,7 @@ module RSpec
           hash
         end
 
-        def self.check_value_type(type, value) # rubocop:disable Metrics/CyclomaticComplexity
+        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)
 

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

@@ -3,7 +3,7 @@
 module RSpec
   module Rails
     module Api
-      VERSION = '0.2.2'
+      VERSION = '0.3.3'
     end
   end
 end

data/rspec-rails-api.gemspec

@@ -32,7 +32,9 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_development_dependency 'activesupport', '>= 5.2'
+  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 'byebug'
   spec.add_development_dependency 'rake', '~> 10.0'

metadata

@@ -1,29 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: rspec-rails-api
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.3
 platform: ruby
 authors:
 - Manuel Tancoigne
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-11-03 00:00:00.000000000 Z
+date: 2021-06-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.2'
+        version: '6.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.2'
+        version: '6.0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -170,7 +170,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.5.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="