rspec-rails-api 0.5.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 232e1ea8b43dd1e3b5258f0029d28a54d886156634e87d4a6854a3543752fb0f
-  data.tar.gz: 71828ab75d08ff900cbe9f018af219bc79b98231118712d127e35c274690d7ad
+  metadata.gz: 4771b145e32ae7cbfd7f03d6252618d3a4cd8b557930a67a562e45046d4e302b
+  data.tar.gz: 6bc0e55b1c2e5d51ba5bdfc52ac532efbf5ad539e138557a99895ef637e0311a
 SHA512:
-  metadata.gz: dbb37718158f52e0a2056bbe9b8ccde44782cafe915cc146f05333532484b10ae8260e7abbd3f571e657c778b8d8ac37c731adfa452d3e94af253dcf6849aede
-  data.tar.gz: 731f623490f7e15b3f0acb8851955835083249b60e62f722ab9870c6658d3e690ed0b6aca8ac4edcdc3f6b1c892517511937d190459b8020fcb2b3c2ef99047a
+  metadata.gz: cafa1ebfc333e41474f85dfb9389f976df1ffa8000de62c8a412c6436088db9182a7f15ec162dff46848265e6cf86564e5a79c93e0814afcc454a242ad77c8b6
+  data.tar.gz: a24717ab5c36a863eaa6939c4ee3f5df3b5fbf058f45b17923d50dd0656680becca60f325d2d9c11b13db84dfaf243a4f24dd77450c33b28911086b986f9cb9e

data/CHANGELOG.md

@@ -1,22 +1,82 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 
-## Not released
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## 0.5.0 - 2023-01-02
+<!--
+Quick remainder of the possible sections:
+-----------------------------------------
+Added, for new features.
+Changed, for changes in existing functionality.
+Deprecated, for soon-to-be removed features.
+Removed, for now removed features.
+Fixed, for any bug fixes.
+Security, in case of vulnerabilities.
+Maintenance, in case of rework, dependencies change
+-->
+
+## [Unreleased]
+
+## [0.6.1] - 2024-01-17
+
+### Fixed
+
+- Renderer: handle arrays of object with inline attributes (not a reference)
+- Renderer: Remove the `name` attribute from `basic` authentication declaration
+- Renderer: Add missing `items` key on arrays of any type 
+
+## [0.6.0] - 2023-07-17
+
+### Added
+
+- Declaring the same resource multiple times is now possible
+- Add a simple support for security schemes
+- Add support for global entities declarations. Keep things DRYer :)
+- `test_response_of`: add `ignore_content_type` flag to ignore response's content type
+- `test_response_of`: add `ignore_response` flag to ignore tests on response
+- Renderer: Add simple support for redactable content. It will replace content in responses by something else. For now, 
+  sub-entities are not redacted.
+- Support for `file` type. When declaring a field with the `file` type, it will change the request content-type to
+  `multipart/form-data` automatically.
+
+### Changed
+
+- Generated JSON files will always be prettified to ease changes reviews when they are versioned
+- When an unexpected 422 error happens, also display its content in error message
+- [BREAKING] It is now impossible to declare the same entity twice. To remediate, rename your declared entities and/or
+  use global declarations. Check [README](./README.md) for example.
+- Renderer: Use response data as-is when it's not valid JSON
+
+### Fixed
+
+- Strip generated descriptions and summaries
+- Primitives are no more referenced in schemas for "expect_one" types
+- Compare type `:float` against `Numeric` class
+- Entities: Raise error when using `:array` type with `attributes` property and `:object` type with `of` property
+- Rendering of sub-references now use the correct reference
+- Metadata: Add missing type on array parameters
+- Don't transform parameters into JSON when making `get` requests
+- Operation IDs don't use summaries for uniqueness
+- Downcase response content type before comparison
+- Type format is now added on request parameters if applicable
+
+## [0.5.0] - 2023-01-02
+
+### Changed
 
 - Improved error messages
 - Improved usage of primitive types: use `:string` instead of `:type_string`, and  more generally, remove the `type_`
   prefix
+
+### Fixed
+- 
 - Fixed an error when an object is defined with an attribute named `type`.
 
-## 0.4.0 - 2021-12-19
+## [0.4.0] - 2021-12-19
+
+### Added
 
-- All parameters attributes are considered required unless specified
-- Fix object `attributes` key in spec and documentation.
-  When defining object attributes, documentation and tests used `properties` key
-  while the code was waiting for an `attributes` key. The later makes more sense
-  so the spec and documentation were fixed.
 - Check for arrays of primitives is now a thing:
   ```rb
   # In entities, when attribute is an array of primitives
@@ -28,15 +88,19 @@ All notable changes to this project will be documented in this file.
     #...
   end
   ```
-- RSpec metadata is now stored in `rra` instead of `rrad` (the gem's first name
-  was RSpec Rails API Doc at the time). Update RSpec configuration accordingly.
 - OpenApi:
   - Responses now includes the schema
   - `on_xxx` methods second parameter is now used as summary instead of description.
     Description can be defined on the third parameter.
+
+### Changed
+
+- All parameters attributes are considered required unless specified
+- RSpec metadata is now stored in `rra` instead of `rrad` (the gem's first name
+  was RSpec Rails API Doc at the time). Update RSpec configuration accordingly.
 - DSL changes:
   - `visit` is renamed to `test_response_of`
-  - Support for `doc_only` is removed 
+  - Support for `doc_only` is removed
   - Response expectations _should_ now be declared with `for_code`, and should be
     removed from example bodies:
     ```rb
@@ -52,44 +116,71 @@ All notable changes to this project will be documented in this file.
     end
     ```
 
+### Fixed
+
+- Fix object `attributes` key in spec and documentation.
+  When defining object attributes, documentation and tests used `properties` key
+  while the code was waiting for an `attributes` key. The later makes more sense
+  so the spec and documentation were fixed.
+
+## [0.3.4] - 2021-10-20
+
+### Added
 
-## 0.3.4 - 2021-10-20
 - Add the "required" attribute in parameters
 
-## 0.3.3 - 2021-06-02
+## [0.3.3] - 2021-06-02
+
+### Fixed
+
 - Fix correct types on request parameters
 
-## 0.3.2 - 2021-03-09
-- Fix YAML rendering (ruby objects were sometimes rendered in documentation)
+## [0.3.2] - 2021-03-09
+
+### Changed
+
 - Render examples results as YAML/JSON objects instead of text blocks.
 
-## 0.3.1 - 2020-04-09
+### Fixed
+
+- Fix YAML rendering (ruby objects were sometimes rendered in documentation)
+
+## [0.3.1] - 2020-04-09
+
+### Added
+
 - Add support for "test only" examples, allowing to write examples without documentation.
 
-## 0.3.0 - 2019-12-26
+## [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
+### Added
 
 - 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
+### Changed
 
-_Version 0.2.1 was released and yanked by mistake. Version 0.2.2 is the exact
-same one, with a version bump_
+- Minimum Ruby version is now specified: Ruby 2.3.3.
+
+## [0.2.2] - 2019-11-03
 
 ### 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
+## [0.2.1] - 2019-11-03 [YANKED]
+
+_Version 0.2.1 was released and yanked by mistake. Version 0.2.2 is the exact
+same one, with a version bump_
+
+## [0.2.0] - 2019-11-02
 
 ### Added
 
@@ -108,35 +199,35 @@ of the fixtures.
   the existing calls accordingly. To use params defined with `parameters`, use the
   `defined` option: `request_params defined: :common_form_params`
 
-## 0.1.5 - 2019-10-31
+## [0.1.5] - 2019-10-31
 
 ### Fixed
 
 - Fixed issue with POST/PUT/DELETE requests with no `request_params`
 - Improved documentation (integration with Devise, typos and mistakes)
 
-## 0.1.4 - 2019-10-24
+## [0.1.4] - 2019-10-24
 
 ### Added
 
 - Added support for arrays of objects in request parameters
 
-## 0.1.3 - 2019-10-23
+## [0.1.3] - 2019-10-23
 
 ### Added
 
 - Added ability to document API descriptions, servers, etc... from the RSpec helper files
 
-## 0.1.2 - 2019-10-22
+## [0.1.2] - 2019-10-22
 
 ### Added
 
 - Added `item` property for arrays descriptions
 
-## 0.1.1 - 2019-10-22
+## [0.1.1] - 2019-10-22
 
 - Added support for custom headers in request examples (useful for `visit` method)
 
-## 0.1.0 - 2019-10-21
+## [0.1.0] - 2019-10-21
 
 Initial release

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rspec-rails-api (0.5.0)
+    rspec-rails-api (0.6.1)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -26,53 +26,114 @@ bundle
 
 Configuration should be made manually for now:
 
-**spec/acceptance_helper.rb**
+**spec/support/rspec_rails_api.rb**:
 
 ```ruby
-require 'rails_helper'
 require 'rspec_rails_api'
 
+# Associate spec/acceptance/* to acceptance tests
+RSpec::Rails::DIRECTORY_MAPPINGS[:acceptance] = %w[spec acceptance]
+
 RSpec.configure do |config|
   config.include RSpec::Rails::Api::DSL::Example
-end
-
-renderer = RSpec::Rails::Api::OpenApiRenderer.new
-# Options here should be customized
-renderer.api_title = 'YourProject API'
-renderer.api_version = '1'
-renderer.api_description = 'Manage data on YourProject'
-# Options below are optional
-renderer.api_servers = [{ url: 'https://example.com' }]
-renderer.api_tos = 'http://example.com/tos.html'
-renderer.api_contact = { name: 'Admin', email: 'admin@example.com', url: 'http://example.com/contact' } 
-renderer.api_license = { name: 'Apache', url: 'https://opensource.org/licenses/Apache-2.0' }
+  config.include RSpec::Rails::RequestExampleGroup, type: :acceptance
 
-RSpec.configuration.after(:context, type: :acceptance) do |context|
-  renderer.merge_context context.class.metadata[:rra].to_h
-end
+  # Define the renderer if you want to generate the OpenApi documentation
+  renderer = RSpec::Rails::Api::OpenApiRenderer.new
+  # Options here should be customized
+  renderer.api_title = 'YourProject API'
+  renderer.api_version = '1'
+  renderer.api_description = 'Manage data on YourProject'
+  # Options below are optional
+  renderer.api_servers = [{ url: 'https://example.com' }]
+  renderer.api_tos = 'http://example.com/tos.html'
+  renderer.api_contact = { name: 'Admin', email: 'admin@example.com', url: 'http://example.com/contact' } 
+  renderer.api_license = { name: 'Apache', url: 'https://opensource.org/licenses/Apache-2.0' }
+  # ... Check the "Configuration" section for all the options
+  
+  config.after(:context, type: :acceptance) do |context|
+    renderer.merge_context context.class.metadata[:rra].to_h
+  end
 
-RSpec.configuration.after(:suite) do
-  # Default path is 'tmp/rspec_rails_api_output.json/yaml'
-  renderer.write_files Rails.root.join('public', 'swagger_doc'), only: [:json]
+  config.after(:suite) do
+    # Default path is 'tmp/rspec_rails_api_output.json/yaml'
+    renderer.write_files Rails.root.join('public', 'swagger_doc'), only: [:json]
+  end
 end
 ```
 
-**spec/rails_helper.rb**
+**spec/rails_helper.rb**:
 
 ```ruby
-# ...
-
-RSpec::Rails::DIRECTORY_MAPPINGS[:acceptance] = %w[spec acceptance]
-
-RSpec.configure do |config|
-  # ...
-  config.include RSpec::Rails::RequestExampleGroup, type: :acceptance
-end
+#...
+require 'support/rspec_rails_api'
+#...
 ```
 
 ## Configuration
 
-**TODO: This section is incomplete and the gem has no generator yet**
+**TODO: This section is incomplete and the gem has no generator yet.**
+
+
+```rb
+# Server URL for quick reference
+server_url = 'https://example.com'
+
+# Options here should be present for a valid OpenAPI file
+renderer.api_title = 'MyProject API'
+renderer.api_version = '1'
+
+# Options below are optional
+# 
+# API description. Markdown supported
+# renderer.api_description = 'Manage data on MyProject'
+#
+# List of servers, to live-test the documentation
+# renderer.api_servers = [{ url: server_url }, { url: 'http://localhost:3000' }]
+#
+# Link to the API terms of service, if any 
+# renderer.api_tos = 'http://example.com/tos.html'
+#
+# Contact information
+# renderer.api_contact = { name: 'Admin', email: 'admin@example.com', url: 'http://example.com/contact' }
+#
+# API license information
+# renderer.api_license = { name: 'Apache', url: 'https://opensource.org/licenses/Apache-2.0' }
+#
+# Possible security schemes
+# renderer.add_security_scheme :pkce_code_grant, 'PKCE code grant',
+#                              type: 'oauth2',
+#                              flows: {
+#                                      implicit: {
+#                                              authorizationUrl: "#{server_url}/oauth/authorize",
+#                                              scopes: { read: 'will read data on your behalf', write: 'will write data on your behalf' }
+#                                      }
+#                              }
+# renderer.add_security_scheme :bearer, 'Bearer token',
+#                              type: 'http',
+#                              scheme: 'bearer'
+#
+# Declare keys whose values should be filtered in responses. 
+# renderer.redact_responses entity_name: { key: 'REDACTED' },
+#                           other_entity: { other_key: ['REDACTED'] }
+
+
+# We need to merge each context metadata so we can reference to them to build the final file
+RSpec.configuration.after(:context, type: :acceptance) do |context|
+  renderer.merge_context context.class.metadata[:rra].to_h
+  # During development of rspec_rails_api, you may want to dump raw metadata to a file
+  renderer.merge_context context.class.metadata[:rra].to_h, dump_metadata: true
+end
+
+# Skip this block if you don't need the OpenAPI documentation file and only have your responses tested
+RSpec.configuration.after(:suite) do
+  renderer.write_files Rails.root.join('public/swagger')                # Write both YAML and prettified JSON files
+  # or
+  renderer.write_files Rails.root.join('public/swagger'), only: [:json] # Prettified JSON only
+  # or
+  renderer.write_files Rails.root.join('public/swagger'), only: [:yaml] # YAML only
+end
+```
 
 ### Integration with Devise
 
@@ -124,7 +185,7 @@ end
 # In examples
 #...
   for_code 200, 'Success' do |url|
-    sing_in #...
+    sign_in #...
     test_response_of url
 
     #...
@@ -135,10 +196,6 @@ end
 This solution comes from [this article](https://makandracards.com/makandra/37161-rspec-devise-how-to-sign-in-users-in-request-specs)
 by Arne Hartherz (MIT license).
 
-## Usage
-
-Write some spec files and run RSpec as you would usually do.
-
 ## Writing specs
 
 There is a [commented example](dummy/spec/acceptance/posts_spec.rb) available in
@@ -149,7 +206,7 @@ The idea is to have a simple DSL, and declare things like:
 **spec/acceptance/users_spec.rb**
 
 ```ruby
-require 'acceptance_helper'
+require 'rails_helper'
 
 RSpec.describe 'Users', type: :acceptance do
   resource 'Users', 'Manage users'
@@ -186,6 +243,80 @@ RSpec.describe 'Users', type: :acceptance do
 end
 ```
 
+### Entity declarations
+
+You can declare entities locally (in every spec files), but sometimes you will need to use/reference the same entity
+in multiple spec files (e.g.: an error message). In that case, you can create _global_ entities in separate files, and they
+will be picked-up when needed.
+
+Example of a local entity:
+
+```rb
+# spec/acceptance/api/users_acceptance_spec.rb
+require 'rails_helper'
+
+RSpec.describe 'Users', type: :acceptance do
+  resource 'Users', 'Manage users'
+
+  # This is a local entity
+  entity :user,
+         id:         { type: :integer, description: 'The id' },
+         email:      { type: :string, description: 'The name' },
+         role:       { type: :string, description: 'The name' },
+         created_at: { type: :datetime, description: 'Creation date' },
+         updated_at: { type: :datetime, description: 'Modification date' },
+         url:        { type: :string, description: 'URL to this category' }
+
+  on_get '/api/users/', 'Users list' do
+    for_code 200, 'Success response', expect_many: :user do |url|
+      test_response_of url
+    end
+  end
+  
+  #...
+end
+```
+
+Defining global entities:
+
+```rb
+# spec/support/entities/user.rb
+# This file should be required at some point in the "rails_helper" or "acceptance_helper"
+
+require 'rspec/rails/api/metadata'
+
+RSpec::Rails::Api::Metadata.add_entity :user,
+                                       id:         { type: :integer, description: 'The id' },
+                                       email:      { type: :string, description: 'The name' },
+                                       role:       { type: :string, description: 'The name' },
+                                       created_at: { type: :datetime, description: 'Creation date' },
+                                       updated_at: { type: :datetime, description: 'Modification date' },
+                                       url:        { type: :string, description: 'URL to this category' }
+
+```
+
+Organization of the global entities declaration is up to you.
+
+For small projects, we usually put them all in one file:
+
+```rb
+# spec/support/acceptance_entities.rb
+
+require 'rspec/rails/api/metadata'
+
+# This file contains common object definitions
+{
+  error: {
+    error: { type: :string, description: "Error message" }
+  },
+  form_error: {
+    title: { type: :array, required: false, description: "Title errors", of: :string }
+  },
+}.each do |name, attributes|
+  RSpec::Rails::Api::Metadata.add_entity name, attributes
+end
+```
+
 ### DSL
 
 #### Example groups
@@ -197,6 +328,23 @@ Starts a resource description.
 - It must be called before any other documentation calls.
 - It should be in the first `describe block`
 
+A resource may be completed across multiple spec files:
+
+```rb
+# an_acceptance_spec.rb
+RSpec.describe 'Something', type: :acceptance do
+  resource 'User', 'Manage users'
+end
+
+# another_acceptance_spec.rb
+RSpec.describe 'Something else', type: :acceptance do
+  resource 'User', 'Another description'
+end
+
+```
+
+The first evaluated `resource` statement will be used as description; all the tests in both files will complete it. 
+
 ##### `entity(type, fields)`
 
 Describes an entity for the documentation. The type is only a reference,
@@ -423,11 +571,30 @@ Once again, you have to pass an argument to the block if you use
 # ...
 ```
 
+##### `requires_security(scheme_references)`
+
+Specifies the valid security schemes to use for this request. Security schemes are declared at the renderer level
+(see [the configuration example](#Configuration)).
+
+```rb
+# Given a previously :basic scheme 
+
+# ...
+  on_get '/some/path' do
+    require_security :basic, :implicit
+    
+    for_code 200 do |url|
+      #...
+    end
+  end
+# ...
+```
+
 #### Examples
 
 Example methods are available in `for_code` blocks
 
-##### `test_response_of(example, path_params: {}, payload: {}, headers: {})`
+##### `test_response_of(example, path_params: {}, payload: {}, headers: {}, ignore_content_type: false)`
 
 Visits the described URL and:
 
@@ -441,6 +608,7 @@ Visits the described URL and:
 - `payload`: a hash of values to send. Ignored for GET and DELETE
   requests
 - `headers`: a hash of custom headers.
+- `ignore_content_type`: whether to ignore response's content-type. By default, checks for a JSON response
 
 ```ruby
 for_code 200, 'Success' do |url|
@@ -543,6 +711,11 @@ MRs to improve this are welcome.
 
 There is no support for file fields yet.
 
+### Security
+
+`Security` mechanisms are only declared for the OpenApi documentation as a reference, and is
+not checked nor enforced in the tests.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies.

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

@@ -9,14 +9,15 @@ module RSpec
           ##
           # Visits the current example and tests the response
           #
-          # @param example     [Hash] Current example
-          # @param path_params [Hash] Path parameters definition
-          # @param payload     [Hash] Request body
-          # @param headers     [Hash] Custom headers
+          # @param example             [Hash] Current example
+          # @param path_params         [Hash] Path parameters definition
+          # @param payload             [Hash] Request body
+          # @param headers             [Hash] Custom headers
+          # @param ignore_content_type [Boolean] Whether to ignore the response's content-type for this response only
           #
           # @return [void]
-          def test_response_of(example, path_params: {}, payload: {}, headers: {}) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
-            raise 'Missing context. Call visit with for_code context.' unless example
+          def test_response_of(example, path_params: {}, payload: {}, headers: {}, ignore_content_type: false, ignore_response: false) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/ParameterLists, Layout/LineLength
+            raise 'Missing context. Call "test_response_of" within a "for_code" block.' unless example
 
             status_code = prepare_status_code example.class.description
 
@@ -25,10 +26,10 @@ module RSpec
 
             send(request_params[:action],
                  request_params[:url],
-                 params:  request_params[:params].to_json,
+                 params:  request_params[:params],
                  headers: request_params[:headers])
 
-            check_response(response, status_code)
+            check_response(response, status_code, ignore_content_type: ignore_content_type) unless ignore_response
 
             return if example.class.description.match?(/-> test (\d+)(.*)/)
 
@@ -38,7 +39,10 @@ module RSpec
           private
 
           ##
-          # Searches for a defined entity in metadata
+          # Searches for a defined entity in example metadata or global entities
+          #
+          # If an entity needs expansion (e.g.: with an attribute like "type: :array, of: :something"), it will use the
+          # scope where the entity was found: global entities or example metadata.
           #
           # @param entity [Symbol] Entity reference
           #
@@ -49,10 +53,10 @@ module RSpec
             current_resource = rra_metadata.current_resource
             raise '@current_resource is unset' unless current_resource
 
-            entities = rra_metadata.resources[current_resource][:entities]
-            raise "Unknown entity '#{entity}' in resource '#{current_resource}'" unless entities.key? entity.to_sym
+            definition = RSpec::Rails::Api::Metadata.entities[entity.to_sym]
+            raise "Entity '#{entity}' was never defined (globally or in '#{current_resource}')" unless definition
 
-            entities[entity.to_sym].expand_with(entities)
+            definition.expand_with(RSpec::Rails::Api::Metadata.entities)
           end
 
           ##
@@ -60,9 +64,21 @@ module RSpec
           #
           # @param response      [ActionDispatch::TestResponse] The response
           # @param expected_code [Number]                       Code to test for
-          def check_response(response, expected_code) # rubocop:disable Metrics/AbcSize
-            expect(response.status).to eq expected_code
-            expect(response.headers['Content-Type']).to eq 'application/json; charset=utf-8' if expected_code != 204
+          # @param ignore_content_type [Boolean]                Whether to ignore the response's content-type for
+          #                                                     this response only
+          def check_response(response, expected_code, ignore_content_type: false) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/CyclomaticComplexity
+            code_error_message = if response.status != expected_code && response.status == 422
+                                   <<~TXT
+                                     expected: #{expected_code}
+                                          got: #{response.status}
+                                     response: #{response.body}
+                                   TXT
+                                 end
+
+            expect(response.status).to eq(expected_code), code_error_message
+            if expected_code != 204 && !ignore_content_type
+              expect(response.headers['Content-Type'].downcase).to eq 'application/json; charset=utf-8'
+            end
             expectations = rra_current_example[:expectations]
             expect(response).to have_many defined(expectations[:many]) if expectations[:many]
             expect(response).to have_one defined(expectations[:one]) if expectations[:one]
@@ -98,9 +114,12 @@ module RSpec
           # @return [Hash] Options for the request
           def prepare_request_params(description, request_params = {}, payload = {}, request_headers = {})
             example_params = description.split
+            verb = example_params[0].downcase
+
+            payload = payload.to_json if verb != 'get'
 
             {
-              action:      example_params[0].downcase,
+              action:      verb,
               url:         prepare_request_url(example_params[1], request_params),
               example_url: example_params[1],
               params:      payload,

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

@@ -28,7 +28,7 @@ module RSpec
           #
           # @return [void]
           def entity(type, fields)
-            metadata[:rra].add_entity type, fields
+            RSpec::Rails::Api::Metadata.add_entity type, fields
           end
 
           ##
@@ -78,6 +78,16 @@ module RSpec
             metadata[:rra].add_request_params attributes
           end
 
+          ##
+          # Declares security schemes valid for this path. It won't be enforced during testing but will complete the
+          # documentation. When the reference does not exist, an exception will be thrown _during_ render, not before.
+          #
+          # @param scheme_references [Array<Symbol>] References to a security scheme defined with the renderer's
+          #                                          `add_security_scheme`.
+          def requires_security(*scheme_references)
+            metadata[:rra].add_security_references(*scheme_references)
+          end
+
           ##
           # Defines a GET action
           #

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

@@ -13,8 +13,8 @@ module RSpec
 
         def initialize(fields)
           @fields = {}
-          fields.each_key do |name|
-            @fields[name] = FieldConfig.new fields[name]
+          fields.each_pair do |name, definition|
+            @fields[name] = FieldConfig.new(**definition)
           end
         end
 

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

@@ -11,10 +11,13 @@ module RSpec
       class FieldConfig
         attr_accessor :required, :type, :attributes, :description
 
-        def initialize(type:, description:, required: true, attributes: nil, of: nil)
+        def initialize(type:, description:, required: true, attributes: nil, of: nil) # rubocop:disable Metrics/CyclomaticComplexity
           @required    = required
           @description = description
+
           raise "Field type not allowed: '#{type}'" unless Validator.valid_type?(type)
+          raise "Don't use 'of' on non-arrays" if of && type != :array
+          raise "Don't use 'attributes' on non-objects" if attributes && type != :object
 
           define_attributes attributes if type == :object
           define_attributes of if type == :array
@@ -50,7 +53,7 @@ module RSpec
         def define_attributes(attributes)
           @attributes = case attributes
                         when Hash
-                          @attributes = EntityConfig.new attributes
+                          EntityConfig.new attributes
                         when Symbol
                           attributes
                         end

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

@@ -10,11 +10,10 @@ module RSpec
     module Api
       # Handles contexts and examples metadata.
       class Metadata # rubocop:disable Metrics/ClassLength
-        attr_reader :entities, :resources, :parameters, :current_resource, :current_url, :current_method, :current_code
+        attr_reader :resources, :parameters, :current_resource, :current_url, :current_method, :current_code
 
         def initialize
           @resources  = {}
-          @entities   = {}
           @parameters = {}
           # Only used when building metadata during RSpec boot
           @current_resource = nil
@@ -23,6 +22,33 @@ module RSpec
           @current_code     = nil
         end
 
+        class << self
+          ##
+          # Define an entity globally.
+          #
+          # Global entities will be available within the specs, but if they are re-declared locally, the local variant
+          # will be used.
+          #
+          # @param name   [Symbol] Entity name
+          # @param fields [Hash]   Fields definitions
+          #
+          # @return [void]
+          def add_entity(name, fields)
+            @entities ||= {}
+            raise "#{name} is already declared" if @entities.key? name
+
+            @entities[name] = EntityConfig.new fields
+          end
+
+          def entities
+            @entities || {}
+          end
+
+          def reset
+            @entities = {}
+          end
+        end
+
         ##
         # Adds a resource to metadata
         #
@@ -31,24 +57,10 @@ module RSpec
         #
         # @return [void]
         def add_resource(name, description)
-          @resources[name.to_sym] = { description: description, paths: {}, entities: {} }
+          @resources[name.to_sym] ||= { description: description, paths: {} }
           @current_resource       = name.to_sym
         end
 
-        ##
-        # 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', name],
-                         EntityConfig.new(fields))
-        end
-
         ##
         # Adds a parameter definition
         #
@@ -61,6 +73,7 @@ module RSpec
 
           fields.each_value do |field|
             field[:required] = true unless field[:required] == false
+            field[:schema] = { type: field[:of] } if field[:type] == :array && PRIMITIVES.include?(field[:of])
           end
           @parameters[name] = fields
         end
@@ -114,6 +127,20 @@ module RSpec
                          params)
         end
 
+        # Associate a defined security scheme to this request
+        #
+        # @param references [Array<Symbol>] Security scheme reference
+        def add_security_references(*references)
+          check_current_context :resource, :url, :method
+
+          refs = @resources.dig @current_resource, 'paths', @current_url, 'actions', @current_method, 'security'
+          refs ||= []
+          refs += references
+          Utils.deep_set(@resources,
+                         [@current_resource, 'paths', @current_url, 'actions', @current_method, 'security'],
+                         refs)
+        end
+
         ##
         # Adds an action and sets `@current_url` and `@current_method`
         #
@@ -294,7 +321,7 @@ module RSpec
         # @param field [Hash] Parameter definition
         #
         # @return [Hash] Completed parameter
-        def fill_request_param(field)
+        def fill_request_param(field) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
           if field[:type] == :object && field[:attributes]
             organize_params field[:attributes]
           else
@@ -302,6 +329,7 @@ module RSpec
               type:        PARAM_TYPES[field[:type]][:type],
               description: field[:description] || nil,
             }
+            properties[:format] = PARAM_TYPES[field[:type]][:format] if PARAM_TYPES[field[:type]][:format]
 
             properties[:items] = organize_params field[:of] if field[:type] == :array && field[:of]
             properties

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

@@ -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 unless reference == :basic
+          @api_security[reference] = definition
         end
 
         ##
@@ -36,7 +56,6 @@ module RSpec
         # @return [void
         def merge_context(context, dump_metadata: false)
           @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'), @metadata.to_yaml if dump_metadata
@@ -54,11 +73,16 @@ module RSpec
 
           path ||= ::Rails.root.join('tmp', 'rspec_api_rails')
 
+          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
 
@@ -77,7 +101,7 @@ module RSpec
             components: @api_components,
             tags:       @api_tags,
           }
-          JSON.parse(JSON.pretty_generate(hash))
+          JSON.parse(hash.to_json)
         end
 
         ##
@@ -125,24 +149,33 @@ module RSpec
         #
         # @return [void]
         def extract_metadata
-          extract_from_resources
+          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
@@ -190,22 +223,31 @@ 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[:items] = { type: field.attributes } if PRIMITIVES.include? field.attributes
+            property[:format] = PARAM_TYPES[field.type][:format] if PARAM_TYPES[field.type][:format]
+
+            if PRIMITIVES.include? field.attributes
+              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}" } }
+            elsif field.type == :array
+              property = { type: :array, items: process_entity(field.attributes) }
+            end
 
             required.push name unless field.required == false
+
+            schema[:properties][name] = property
           end
 
           schema[:required] = required unless required.size.zero?
@@ -221,10 +263,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:      {
@@ -250,7 +292,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
@@ -268,21 +310,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
@@ -294,11 +346,12 @@ module RSpec
         # @return [void]
         def process_request_body(schema: nil, ref: nil, examples: {})
           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,
               },
@@ -306,6 +359,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
         #
@@ -314,22 +384,45 @@ 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, Metrics/PerceivedComplexity
           if expectations[:many]
             items = if PRIMITIVES.include?(expectations[:many])
                       { type: expectations[:many] }
@@ -338,7 +431,15 @@ module RSpec
                     end
             { type: 'array', items: items }
           elsif expectations[:one]
-            { '$ref' => "#/components/schemas/#{expectations[:one]}" }
+            # Unspecified arrays
+            if expectations[:one] == :array
+              { type: :array, items: {} }
+            # Array of specified type
+            elsif PRIMITIVES.include?(expectations[:one])
+              { type: expectations[:one] }
+            else
+              { '$ref' => "#/components/schemas/#{expectations[:one]}" }
+            end
           end
         end
 
@@ -361,6 +462,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
         #
@@ -387,12 +498,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/version.rb

@@ -3,7 +3,7 @@
 module RSpec
   module Rails
     module Api
-      VERSION = '0.5.0'
+      VERSION = '0.6.1'
     end
   end
 end

data/lib/rspec_rails_api.rb

@@ -30,9 +30,10 @@ module RSpec
         boolean:  { type: 'boolean', format: nil },
         string:   { type: 'string', format: nil, class: String },
         integer:  { type: 'integer', format: nil, class: Integer },
-        number:   { type: 'number', format: nil, class: Float },
+        number:   { type: 'number', format: nil, class: Numeric },
         array:    { type: 'array', format: nil, class: Array },
         object:   { type: 'object', format: nil, class: Hash },
+        file:     { type: 'string', format: 'binary' },
       }.freeze
 
       PRIMITIVES = PARAM_TYPES.keys

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rspec-rails-api
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.1
 platform: ruby
 authors:
 - Manuel Tancoigne
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-01-02 00:00:00.000000000 Z
+date: 2024-01-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport