rspec-rails-api 0.3.4 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9090792ade8b44f18851585ce025a354fab47ff9cb7903ae61982507c34302bf
-  data.tar.gz: 26551e11739758d40987f7026cc556e475952f79419cb24abf5df4207ba40364
+  metadata.gz: 06e9bc31ff4e310ca952011e76cc3fb6dcc39b15ea090229edb1385b51ed16f6
+  data.tar.gz: 8be9cba238ce37496e2e7eb2db221754cde5c673b1e404541ea84e71095e6ccb
 SHA512:
-  metadata.gz: 4bc1803ab38dc596f0fbf3993da2f860e22849f1d2e9c68be91e860b36684ee3bf0129a98972afca1d7f65869531c6cc8aa0f36d66aa91d97f92ebbad69cfff1
-  data.tar.gz: b96392b596dd83d1de832b62a72d54afbed0f0a556c36bbf7627ed2fbec7c36d59c4d1d935186e3de62f72524243bf75f92a6429bc492cf559ebb22751e74dcc
+  metadata.gz: 5a9058a1121e702991d55696687b64cb8d2bb3872596b4d92f79aa33de8ef54a5b9ef33d2275f92087256cd6d7afcd1fc16472157d52529e19a97b5b66118b70
+  data.tar.gz: 85777059873dd5fba1842ce286c0c0c4c445aa2dad584a2992b2add593de51cb267e1b398dd6038fe71f5ec36bfa38bf8f03fa4ce0877d0438ae62f4f58fb82f

data/CHANGELOG.md

@@ -2,6 +2,48 @@
 All notable changes to this project will be documented in this file.
 
 ## Not released
+
+- 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
+  entity :user,
+         aliases: { type: :array, description: 'Pseudonyms', of: :type_string }
+
+  # In examples, when response is an array of primitives
+  for_code 200, expect_many: :type_string do |url|
+    #...
+  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.
+- DSL changes:
+  - `visit` is renamed to `test_response_of`
+  - Support for `doc_only` is removed 
+  - Response expectations _should_ now be declared with `for_code`, and should be
+    removed from example bodies:
+    ```rb
+    # Before:
+    for_code 200 do |url|
+      visit url
+      expect(response).to have_many defined: :post
+    end
+    
+    # Now:
+    for_code 200, expect_many: :post do |url|
+      test_response_of url
+    end
+    ```
+
+
 ## 0.3.4 - 2021-10-20
 - Add the "required" attribute in parameters
 

data/README.md

@@ -48,7 +48,7 @@ renderer.api_contact = { name: 'Admin', email: 'admin@example.com', url: 'http:/
 renderer.api_license = { name: 'Apache', url: 'https://opensource.org/licenses/Apache-2.0' }
 
 RSpec.configuration.after(:context, type: :acceptance) do |context|
-  renderer.merge_context context.class.metadata[:rrad].to_h
+  renderer.merge_context context.class.metadata[:rra].to_h
 end
 
 RSpec.configuration.after(:suite) do
@@ -125,7 +125,7 @@ end
 #...
   for_code 200, 'Success' do |url|
     sing_in #...
-    visit url
+    test_response_of url
 
     #...
   end
@@ -139,14 +139,6 @@ by Arne Hartherz (MIT license).
 
 Write some spec files and run RSpec as you would usually do.
 
-If you want to generate the documentation without testing the endpoints
-(and thus, without examples in generated files), use the `DOC_ONLY`
-environment variable:
-
-```sh
-DOC_ONLY=true bundle exec rails spec
-```
-
 ## Writing specs
 
 There is a [commented example](dummy/spec/acceptance/posts_spec.rb) available in
@@ -171,9 +163,8 @@ RSpec.describe 'Users', type: :acceptance do
          url:        { type: :string, description: 'URL to this category' }
 
   on_get '/api/users/', 'Users list' do
-    for_code 200, 'Success response' do |url|
-      visit url
-      expect(response).to have_many defined :user
+    for_code 200, 'Success response', expect_many: :user do |url|
+      test_response_of url
     end
   end
 
@@ -181,16 +172,15 @@ RSpec.describe 'Users', type: :acceptance do
     path_param id: { type: :integer, description: 'User Id' }
 
     request_params user: {
-      type: :object, required: true, properties: {
+      type: :object, attributes: {
         name:  { type: :string, required: false, description: 'New name' },
         email: { type: :string, required: false, description: 'New email' },
         role:  { type: :string, required: false, description: 'New role' },
       }
     }
 
-    for_code 200, 'Success response' do |url|
-      visit url
-      expect(response).to have_one defined :user
+    for_code 200, 'Success response', expect_one: :user do |url|
+      test_response_of url
     end
   end
 end
@@ -273,6 +263,16 @@ 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:
+
+```rb
+entity :user,
+       surnames: { type: :array, of: :type_int32 }
+```
+
+Check `lib/rspec_rails_api.rb` for the full list.
+
 ##### `parameters(type, fields)`
 Describe path or request parameters. The type is only a reference,
 use whatever makes sense. These parameters will be present in
@@ -282,16 +282,16 @@ documentation, only if they are referenced by a `request_params` or
 Fields have the structure of the hash you would give to `request_params`
 or `path_params` (see each method later in this documentation).
 
-##### `on_<xxx>(url, description, &block)`
+##### `on_<xxx>(url, summary = nil, description = nil, &block)`
 
 Defines an URL.
 
 - `url` should be a relative URL to an existing endpoint (i.e.:
   `/api/users`)
-- `description` should be some valid
-  [CommonMark](https://commonmark.org/)
+- `summary` is a one line description of the endpoint
+- `description` should be some valid [CommonMark](https://commonmark.org/)
 
-For now, only these methods are available:
+These methods are available:
 
 - `on_get`
 - `on_post`
@@ -341,7 +341,7 @@ nested elements can be described:
 ```ruby
 on_post '/api/items' do
   request_params attributes: {
-                   item: { type: :object, required: true, properties: {
+                   item: { type: :object, attributes: {
                      name: { type: integer, description: 'The name of the new item', required: true },
                      notes: { type: string, description: 'Additional notes' }
                      } }
@@ -353,21 +353,21 @@ end
 An attribute should have the following form:
 
 ```
-<attr_name>: {type: <type>, desc: <description>, required: <required>, properties: <another_hash>, of: <another_hash> }
+<attr_name>: {type: <type>, desc: <description>, required: <required>, attributes: <another_hash>, of: <another_hash> }
 ```
 
 - `attr_name` is the attribute name (sic)
 - `type` is the field type (check _entity definition_ for a list).
   `type` can be `:object` if the attribute contains other attributes.
 - `required` is optional an defaults to `false`.
-- `properties` is a hash of params and is only used if `type: :object`
+- `attributes` is a hash of params and is only used if `type: :object`
 - `of` is a hash of params and is only used if `type: :array`
 
 Alternative with defined parameters:
 
 ```ruby
 parameters :item_form_params,
-           item: { type: :object, required: true, properties: {
+           item: { type: :object, attributes: {
               name: { type: integer, description: 'The name of the new item', required: true },
               notes: { type: string, description: 'Additional notes' }
              }
@@ -380,12 +380,12 @@ on_post '/api/items' do
 end
 ```
 
-##### `for_code(http_status, description = nil, doc_only: false, test_only: false &block)`
+##### `for_code(http_status, description = nil, test_only: false &block)`
 
 Describes the desired output for a precedently defined URL.
 
-Block takes one required argument, that should be passed to `visit`.
-This argument will contain the block context and allow `visit` to access
+Block takes one required argument, that should be passed to `test_response_of`.
+This argument will contain the block context and allow `test_response_of` to access
 the metadatas.
 
 You can have only one documented code per action/url, unless you use
@@ -396,11 +396,9 @@ You can have only one documented code per action/url, unless you use
 - `description` should be some valid
   [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
+- `block` where additional tests can be performed. If `test_response_of` is
   called within the block, its output will be used in documentation
   examples, and the response type and code will actually be tested.
 
@@ -409,17 +407,17 @@ examples. This can be useful to document endpoints that are impossible
 to test.
 
 Once again, you have to pass an argument to the block if you use
-`visit`.
+`test_response_of`.
 
 ```ruby
 # ...
   for_code 200, 'A successful response' do |url|
-    visit url
+    test_response_of url
     # ...
   end
   
   for_code 200, 'Side test', test_only: true do |url|
-    visit url
+    test_response_of url
     # ...
   end
 # ...
@@ -429,7 +427,7 @@ Once again, you have to pass an argument to the block if you use
 
 Example methods are available in `for_code` blocks
 
-##### `visit(example, path_params: {}, payload: {}, headers: {})`
+##### `test_response_of(example, path_params: {}, payload: {}, headers: {})`
 
 Visits the described URL and:
 
@@ -446,12 +444,17 @@ Visits the described URL and:
 
 ```ruby
 for_code 200, 'Success' do |url|
-  visit url
+  test_response_of url
 end
 ```
 
 #### Matchers
 
+The matchers _should not_ be used in acceptance specs unless the default DSL is
+not adapted for a particular use case (and I can't imagine one now).
+
+For the sake of comprehension, the two custom matchers still described.
+
 ##### `have_one(type)`
 
 Expects the compared content to be a hash with the same keys as a

data/Rakefile

@@ -2,7 +2,10 @@
 
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
+require 'yard'
 
 RSpec::Core::RakeTask.new(:spec)
 
 task default: :spec
+
+YARD::Rake::YardocTask.new

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

@@ -6,7 +6,16 @@ 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, Metrics/MethodLength
+          ##
+          # 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
+          #
+          # @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
 
             status_code = prepare_status_code example.class.description
@@ -23,37 +32,72 @@ module RSpec
 
             return if example.class.description.match?(/-> test (\d+)(.*)/)
 
-            set_request_example example.class.metadata[:rrad], request_params, status_code, response.body
+            set_request_example example.class.metadata[:rra], request_params, status_code, response.body
           end
 
+          private
+
+          ##
+          # Searches for a defined entity in metadata
+          #
+          # @param entity [Symbol] Entity reference
+          #
+          # @return [RSpec::Rails::Api::EntityConfig, Hash] Defined entity
           def defined(entity)
-            current_resource = self.class.metadata[:rrad].current_resource
+            return { type: entity.to_s.split('_').last.to_sym } if PRIMITIVES.include? entity
+
+            current_resource = rra_metadata.current_resource
             raise '@current_resource is unset' unless current_resource
 
-            entities = self.class.metadata[:rrad].resources[current_resource][:entities]
+            entities = rra_metadata.resources[current_resource][:entities]
 
             out = entities[entity]
-            raise "Unkown entity '#{entity}' in resource '#{current_resource}'" unless out
+            raise "Unknown entity '#{entity}' in resource '#{current_resource}'" unless out
 
             out.expand_with(entities)
           end
 
-          private
-
-          def check_response(response, expected_code)
+          ##
+          # Performs various tests on the response
+          #
+          # @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
+            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]
+            expect(response.body).to eq '' if expectations[:none]
           end
 
-          def set_request_example(rrad_metadata, request_params, status_code = nil, response = nil)
-            rrad_metadata.add_request_example(url:         request_params[:example_url],
-                                              action:      request_params[:action],
-                                              status_code: status_code,
-                                              response:    response,
-                                              path_params: request_params[:path_params],
-                                              params:      request_params[:params])
+          ##
+          # Adds a request example information to metadata
+          #
+          # @param rra_metadata  [RSpec::Rails::Api::Metadata]
+          # @param request_params [Hash]
+          # @param status_code    [Integer, nil]
+          # @param response       [String, nil]
+          #
+          # @return [void]
+          def set_request_example(rra_metadata, request_params, status_code = nil, response = nil)
+            rra_metadata.add_request_example(url:         request_params[:example_url],
+                                             action:      request_params[:action],
+                                             status_code: status_code,
+                                             response:    response,
+                                             path_params: request_params[:path_params],
+                                             params:      request_params[:params])
           end
 
+          ##
+          # Prepares the options for a request
+          #
+          # @param description     [String] RSpec example description
+          # @param request_params  [Hash]   Request parameters
+          # @param payload         [Hash]   Request body
+          # @param request_headers [Hash]   Custom headers
+          #
+          # @return [Hash] Options for the request
           def prepare_request_params(description, request_params = {}, payload = {}, request_headers = {})
             example_params = description.split
 
@@ -66,7 +110,13 @@ module RSpec
             }
           end
 
+          ##
           # Replace path params by values
+          #
+          # @param url            [String] Url definition
+          # @param request_params [Hash]   Request parameters
+          #
+          # @return [String] Actual path to visit
           def prepare_request_url(url, request_params)
             url.gsub(/(?::(\w*))/) do |e|
               symbol = e.sub(':', '').to_sym
@@ -80,6 +130,12 @@ module RSpec
             end
           end
 
+          ##
+          # Prepares request headers
+          #
+          # @param headers [Hash] Custom headers
+          #
+          # @return [Hash] Headers to use in request
           def prepare_request_headers(headers = {})
             {
               'Accept'       => 'application/json',
@@ -87,6 +143,12 @@ module RSpec
             }.merge headers
           end
 
+          ##
+          # Extracts status code from RSpec example description
+          #
+          # @param description [String] RSpec example description
+          #
+          # @return [Integer] Status code
           def prepare_status_code(description)
             code_match = /->(?: test)? (\d+) - .*/.match description
 
@@ -94,6 +156,22 @@ module RSpec
 
             code_match[1].to_i
           end
+
+          ##
+          # Returns the current example configuration from metadata
+          #
+          # @return [Hash] Current example configuration
+          def rra_current_example
+            self.class.metadata[:rra_current_example]
+          end
+
+          ##
+          # Returns the whole Rspec-rails-API metadata object
+          #
+          # @return [RSpec::Rails::Api::Metadata] Rspec-rails-API metadata object
+          def rra_metadata
+            self.class.metadata[:rra]
+          end
         end
       end
     end