rspec-rails-api 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 06e9bc31ff4e310ca952011e76cc3fb6dcc39b15ea090229edb1385b51ed16f6
-  data.tar.gz: 8be9cba238ce37496e2e7eb2db221754cde5c673b1e404541ea84e71095e6ccb
+  metadata.gz: aa6db3329e09e4356d205cf49f100e11132a3e8a8fcb681ef8ede5e22ba470dd
+  data.tar.gz: e25b15faecc41214f92bb089f8fc9e28702f9c5ad2072daf4014251d30f23291
 SHA512:
-  metadata.gz: 5a9058a1121e702991d55696687b64cb8d2bb3872596b4d92f79aa33de8ef54a5b9ef33d2275f92087256cd6d7afcd1fc16472157d52529e19a97b5b66118b70
-  data.tar.gz: 85777059873dd5fba1842ce286c0c0c4c445aa2dad584a2992b2add593de51cb267e1b398dd6038fe71f5ec36bfa38bf8f03fa4ce0877d0438ae62f4f58fb82f
+  metadata.gz: 2c947cf296de131ece545c7a21ed093d79de1e1fd5f57af53c58985eab815c781ce4dcbba7f7269c679dbf8155d4eabf0ae5035caa70bbd88090650630ed8e11
+  data.tar.gz: b0c4d8bef1c715b0ea369b5f7a659e8fa69344735af2a7735a51a1cb755c3fc3b642597c47a133be9568c0361d8565725ed803d2b0dd530050d1e286795ee911

data/.gitignore

@@ -10,9 +10,4 @@
 # rspec failure tracking
 .rspec_status
 
-# Ignore lockfile for Gemfile
-Gemfile.lock
-# Keep the dummy one
-!dummy/Gemfile.lock
-
 .byebug_history

data/.gitlab-ci.yml

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

data/.rubocop.yml

@@ -1,9 +1,11 @@
 ---
 require:
   - rubocop-performance
+  - rubocop-rake
+  - rubocop-rspec
 
 AllCops:
-  TargetRubyVersion: 2.5
+  TargetRubyVersion: 2.7
   Exclude:
     - dummy/**/*
     - vendor/bundle/**/*
@@ -33,3 +35,5 @@ Style/TrailingCommaInArrayLiteral:
 Style/TrailingCommaInHashLiteral:
   EnforcedStyleForMultiline: comma
 
+RSpec/NestedGroups:
+  Max: 4

data/.ruby-version

@@ -0,0 +1 @@
+2.7.0

data/CHANGELOG.md

@@ -1,13 +1,74 @@
 # 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).
+
+<!--
+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.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
+
+### 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
@@ -19,15 +80,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
@@ -43,44 +108,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
 
@@ -99,35 +191,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

@@ -0,0 +1,98 @@
+PATH
+  remote: .
+  specs:
+    rspec-rails-api (0.6.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (6.1.7)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+      zeitwerk (~> 2.3)
+    ast (2.4.2)
+    byebug (11.1.3)
+    concurrent-ruby (1.1.10)
+    diff-lcs (1.5.0)
+    docile (1.4.0)
+    i18n (1.12.0)
+      concurrent-ruby (~> 1.0)
+    json (2.6.3)
+    minitest (5.16.3)
+    parallel (1.22.1)
+    parser (3.1.3.0)
+      ast (~> 2.4.1)
+    rack (3.0.3)
+    rainbow (3.1.1)
+    rake (10.5.0)
+    regexp_parser (2.6.1)
+    rexml (3.2.5)
+    rspec (3.12.0)
+      rspec-core (~> 3.12.0)
+      rspec-expectations (~> 3.12.0)
+      rspec-mocks (~> 3.12.0)
+    rspec-core (3.12.0)
+      rspec-support (~> 3.12.0)
+    rspec-expectations (3.12.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-mocks (3.12.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-support (3.12.0)
+    rubocop (1.41.1)
+      json (~> 2.3)
+      parallel (~> 1.10)
+      parser (>= 3.1.2.1)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.23.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 3.0)
+    rubocop-ast (1.24.1)
+      parser (>= 3.1.1.0)
+    rubocop-performance (1.15.2)
+      rubocop (>= 1.7.0, < 2.0)
+      rubocop-ast (>= 0.4.0)
+    rubocop-rake (0.6.0)
+      rubocop (~> 1.0)
+    rubocop-rspec (2.16.0)
+      rubocop (~> 1.33)
+    ruby-progressbar (1.11.0)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.12.3)
+    simplecov_json_formatter (0.1.4)
+    tzinfo (2.0.5)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (2.3.0)
+    webrick (1.7.0)
+    yard (0.9.28)
+      webrick (~> 1.7.0)
+    zeitwerk (2.6.6)
+
+PLATFORMS
+  x86_64-linux
+
+DEPENDENCIES
+  activesupport (~> 6.0)
+  bundler
+  byebug
+  rack
+  rake (~> 10.0)
+  rspec (~> 3.0)
+  rspec-rails-api!
+  rubocop
+  rubocop-performance
+  rubocop-rake
+  rubocop-rspec
+  simplecov
+  yard
+
+BUNDLED WITH
+   2.4.1

data/README.md

@@ -72,7 +72,101 @@ end
 
 ## 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.**
+
+Here is an example configuration:
+
+```rb
+# spec/rails_helper.rb
+require 'spec/support/rspec_rails_api'
+```
+
+```rb
+# spec/support/acceptance_entities.rb
+
+# 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
+```
+
+```rb
+# spec/support/rspec_rails_api.rb
+require 'rspec_rails_api'
+require 'support/acceptance_entities'
+
+# Include DSL in RSpec
+RSpec.configure do |config|
+  config.include RSpec::Rails::Api::DSL::Example
+end
+
+# Initialize and configure the renderer
+renderer = RSpec::Rails::Api::OpenApiRenderer.new
+# 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 +218,7 @@ end
 # In examples
 #...
   for_code 200, 'Success' do |url|
-    sing_in #...
+    sign_in #...
     test_response_of url
 
     #...
@@ -149,7 +243,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 +280,78 @@ 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.
+
+```rb
+# spec/acceptance/api/users_acceptance_spec.rb
+require 'rails_helper'
+
+RSpec.describe 'Users', type: :acceptance do
+  resource 'Users', 'Manage users'
+
+  on_get '/api/users/', 'Users list' do
+    # "user" will use the global user entity
+    for_code 200, 'Success response', expect_many: :user do |url|
+      test_response_of url
+    end
+  end
+  
+  #...
+end
+```
+
 ### DSL
 
 #### Example groups
@@ -197,6 +363,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,
@@ -263,12 +446,12 @@ inline.
 Both `:of` and `attributes` may be a hash of fields or a symbol. If they
 are omitted, they will be documented, but responses won't be validated.
 
-Arrays of primitives are supported; the type should be prefixed by `type_` to 
-avoid collisions with defined entities of the same name:
+Arrays of primitives are supported; refer to the [documentation](https://swagger.io/specification/#data-types) for the 
+list. Usage:
 
 ```rb
 entity :user,
-       surnames: { type: :array, of: :type_int32 }
+       favorite_numbers: { type: :array, of: :int32 }
 ```
 
 Check `lib/rspec_rails_api.rb` for the full list.
@@ -423,11 +606,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 +643,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|