rspec-rails-api 0.2.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0861008371cafa6cab0cda5c165acda54b5a3047f152713bb684ae0c7c7be0ff'
-  data.tar.gz: d3c8877c5ef1e43c902010b68b9e483feefa6e57251d67aba325394a9682aee7
+  metadata.gz: d574f6e06c94fc87d2db77079f80a341da7455b5776c3513a7e84b5b80165090
+  data.tar.gz: 23ddbfe59c098baa1ffcec4dce21d5d6ba25f8fe0143d965d11a8bee25771aad
 SHA512:
-  metadata.gz: e1009f40d78187888e546c74e62e88d7557f45a4a3cfed78a27785d63b401f673ed1796928f1d32823a665694b86761653bb87edc68522418d6117c4b576e362
-  data.tar.gz: 10ffebb4902456c4671b39b7dd707ea8ca870b9a27054c3139cae94bb3dcebfc3f88abd41a298ed870f98d7953c1195171cbf8f077db2dcd6530fe761e354a5a
+  metadata.gz: 3430d1d5da42f6c7bf9d28f6c6e6a74ff332fb3cd31cf92d170d9c87f76527dd0d64d6ae510ae19873d7ca078c4405a05154d867f100f804e806c6e6fc342049
+  data.tar.gz: f251c30d40efaeef76bfd3ea0f313834dc7323ab56dc07ddf1ecc845b033160dd29afd053d3de3b0a2d7afee7092e858a1844795296e6593d9598f0d17f4df58

data/.gitlab-ci.yml

@@ -1,5 +1,5 @@
 ---
-image: ruby:2.4
+image: ruby:2.5
 
 stages:
   - prepare
@@ -35,9 +35,10 @@ rspec:
   dependencies:
     - bundle
 
-rspec-dummy:
+dummy:
   stage: test
   script:
     - cd dummy
     - bundle install --path='vendor/bundle'
+    - bundle exec rubocop
     - bundle exec rspec

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,36 @@ 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
+same one, with a version bump_
+
+### Changed
+
+- `for_code` method now have its `description` optional. If none is provided,
+  the description will be set from the status code.
+
 ## 0.2.0 - 2019-11-02
 
 ### Added
@@ -40,7 +70,7 @@ of the fixtures.
 ### Added
 
 - Added ability to document API descriptions, servers, etc... from the RSpec helper files
-  
+
 ## 0.1.2 - 2019-10-22
 
 ### Added

data/README.md

@@ -1,15 +1,14 @@
 # RSpec-rails-api
 
-> An RSpec plugin to test Rails api responses and generate swagger
+> An RSpec plugin to test Rails API responses and generate swagger
 > documentation
 
 **This is a work in progress** but you're welcome to help, test, submit
 issues, ...
 
-## Installation
+**Note** For Rails 5, use version 0.2.3
 
-As the gem is not yet published, you have to specify its git repository
-in order to test it.
+## Installation
 
 Add this line to your application's Gemfile:
 
@@ -381,7 +380,7 @@ on_post '/api/items' do
 end
 ```
 
-##### `for_code(http_status, description, 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.
 
@@ -389,12 +388,18 @@ 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
-  [CommonMark](https://commonmark.org/)
+  [CommonMark](https://commonmark.org/). If not defined, a human readable
+  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.
@@ -412,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,17 +74,13 @@ module RSpec
             describe("#{action.upcase} #{url}", &block)
           end
 
-          def for_code(status_code, description, doc_only: false, &block)
-            metadata[:rrad].add_status_code(status_code, description)
-
-            describe "-> #{status_code} - #{description}" do
-              if (!ENV['DOC_ONLY'] || ENV['DOC_ONLY'] == 'false' || !doc_only) && block
-                example 'Test and create documentation', caller: block.send(:caller) do
-                  instance_eval(&block) if block_given?
-                end
-              else
-                document_only status_code
-              end
+          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) unless test_only
+
+            describe "->#{test_only ? ' test' : ''} #{status_code} - #{description}" do
+              execute_for_code_block(status_code, doc_only, block)
             end
           end
 
@@ -93,11 +89,21 @@ 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
           end
+
+          def execute_for_code_block(status_code, doc_only, callback_block)
+            if (!ENV['DOC_ONLY'] || ENV['DOC_ONLY'] == 'false' || !doc_only) && callback_block
+              example 'Test and create documentation', caller: callback_block.send(:caller) do
+                instance_eval(&callback_block) if callback_block
+              end
+            else
+              document_only status_code
+            end
+          end
         end
       end
     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]

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.0'
+      VERSION = '0.3.2'
     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.0
+  version: 0.3.2
 platform: ruby
 authors:
 - Manuel Tancoigne
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-11-02 00:00:00.000000000 Z
+date: 2021-03-09 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:
   - - ">="