Add the contract DSL

.github/workflows/test.yml

@@ -25,13 +25,17 @@ jobs:
       matrix:
         ruby: ['2.7', '3.0', '3.1', '3.2', '3.3']
         gemfile: [rack_2_0, rack_3_0, rails_6_0, rails_6_1, rails_7_0, rails_7_1]
+        integration_only: false
         include:
           - ruby: '2.7'
             gemfile: rack_1_0
           - ruby: '2.7'
             gemfile: multi_json
           - ruby: '2.7'
             gemfile: multi_xml
+          - ruby: '3.3'
+            gemfile: no_dry_validation
+            integration_only: true
     runs-on: ubuntu-latest
     env:
       BUNDLE_GEMFILE: ${{ github.workspace }}/gemfiles/${{ matrix.gemfile }}.gemfile
@@ -45,6 +49,7 @@ jobs:
         bundler-cache: true
 
     - name: Run tests
+      if: ${{ matrix.integration_only == false }}
       run: bundle exec rake spec
 
     - name: Run tests (spec/integration/eager_load)
@@ -70,6 +75,10 @@ jobs:
       if: ${{ matrix.gemfile == 'rack_3_0' }}
       run: bundle exec rspec spec/integration/rack/v3
 
+    - name: Run tests (spec/integration/no_dry_validation)
+      if: ${{ matrix.gemfile == 'no_dry_validation' }}
+      run: bundle exec rspec spec/integration/no_dry_validation
+
     - name: Coveralls
       uses: coverallsapp/github-action@master
       with:

.rubocop_todo.yml

@@ -392,6 +392,7 @@ RSpec/MultipleExpectations:
     - 'spec/grape/util/reverse_stackable_values_spec.rb'
     - 'spec/grape/util/stackable_values_spec.rb'
     - 'spec/grape/validations/attributes_doc_spec.rb'
+    - 'spec/grape/validations/contract_scope_spec.rb'
     - 'spec/grape/validations/instance_behaivour_spec.rb'
     - 'spec/grape/validations/params_scope_spec.rb'
     - 'spec/grape/validations/types/array_coercer_spec.rb'

Appraisals

@@ -1,19 +1,24 @@
 # frozen_string_literal: true
 
-appraise 'rails-5' do
-  gem 'rails', '~> 5.2'
+customize_gemfiles do
+  {
+    single_quotes: true,
+    heading: "frozen_string_literal: true
+
+This file was generated by Appraisal"
+  }
 end
 
-appraise 'rails-6' do
+appraise 'rails-6-0' do
   gem 'rails', '~> 6.0.0'
 end
 
 appraise 'rails-6-1' do
   gem 'rails', '~> 6.1'
 end
 
-appraise 'rails-7' do
-  gem 'rails', '~> 7.0'
+appraise 'rails-7-0' do
+  gem 'rails', '~> 7.0.0'
 end
 
 appraise 'rails-edge' do
@@ -32,14 +37,20 @@ appraise 'multi_xml' do
   gem 'multi_xml', require: 'multi_xml'
 end
 
-appraise 'rack1' do
+appraise 'rack_1_0' do
   gem 'rack', '~> 1.0'
 end
 
-appraise 'rack2' do
-  gem 'rack', '~> 2.0.0'
+appraise 'rack_2_0' do
+  gem 'rack', '~> 2.0'
 end
 
-appraise 'rack3' do
+appraise 'rack_3_0' do
   gem 'rack', '~> 3.0.0'
 end
+
+appraise 'no_dry_validation' do
+  group :development, :test do
+    remove_gem 'dry-validation'
+  end
+end

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 #### Features
 
+* [#2419](https://github.com/ruby-grape/grape/pull/2419): Add the `contract` DSL - [@dgutov](https://github.com/dgutov).
 * [#2371](https://github.com/ruby-grape/grape/pull/2371): Use a param value as the `default` value of other param - [@jcagarcia](https://github.com/jcagarcia).
 * [#2377](https://github.com/ruby-grape/grape/pull/2377): Allow to use instance variables values inside `rescue_from` - [@jcagarcia](https://github.com/jcagarcia).
 * [#2379](https://github.com/ruby-grape/grape/pull/2379): Take into account the `route_param` type in `recognize_path` - [@jcagarcia](https://github.com/jcagarcia).

Gemfile

@@ -9,6 +9,7 @@ gemspec
 group :development, :test do
   gem 'bundler'
   gem 'hashie'
+  gem 'dry-validation'
   gem 'rake'
   gem 'rubocop', '1.59.0', require: false
   gem 'rubocop-performance', '1.20.1', require: false

README.md

@@ -77,6 +77,7 @@
     - [Pass symbols for i18n translations](#pass-symbols-for-i18n-translations)
     - [Overriding Attribute Names](#overriding-attribute-names)
     - [With Default](#with-default)
+  - [Using `dry-validation` or `dry-schema`](#using-dry-validation-or-dry-schema)
 - [Headers](#headers)
   - [Request](#request)
     - [Header Case Handling](#header-case-handling)
@@ -2086,6 +2087,31 @@ params do
 end
 ```
 
+### Using `dry-validation` or `dry-schema`
+
+As an alternative to the `params` DSL described above, you can use a schema or `dry-validation` contract to describe an endpoint's parameters. This can be especially useful if you use the above already in some other parts of your application. If not, you'll need to add `dry-validation` or `dry-schema` to your `Gemfile`.
+
+Then call `contract` with a contract or schema defined previously
+
+```rb
+contract CreateFoosSchema
+```
+
+or with a block, using the [schema definition syntax](https://dry-rb.org/gems/dry-schema/1.13/#quick-start):
+
+```rb
+contract do
+  required(:foos).array do
+    required(:name).filled(:string)
+    optional(:volume).maybe(:integer, lt?: 9)
+  end
+end
+```
+
+The latter will define a coercing schema (`Dry::Schema.Params`). When using the former approach, it's up to you to decide whether the input will need coercing.
+
+`params` and `contract` declarations can also be used together, e.g. to describe different parts of a nested namespace for an endpoint.
+
 ## Headers
 
 ### Request

gemfiles/multi_json.gemfile

@@ -9,6 +9,7 @@ gem 'multi_json', require: 'multi_json'
 group :development, :test do
   gem 'bundler'
   gem 'hashie'
+  gem 'dry-validation'
   gem 'rake'
   gem 'rubocop', '1.59.0', require: false
   gem 'rubocop-performance', '1.20.1', require: false

gemfiles/multi_xml.gemfile

@@ -9,6 +9,7 @@ gem 'multi_xml', require: 'multi_xml'
 group :development, :test do
   gem 'bundler'
   gem 'hashie'
+  gem 'dry-validation'
   gem 'rake'
   gem 'rubocop', '1.59.0', require: false
   gem 'rubocop-performance', '1.20.1', require: false

gemfiles/no_dry_validation.gemfile

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# This file was generated by Appraisal
+
+source 'https://rubygems.org'
+
+group :development, :test do
+  gem 'bundler'
+  gem 'hashie'
+  gem 'rake'
+  gem 'rubocop', '1.59.0', require: false
+  gem 'rubocop-performance', '1.20.1', require: false
+  gem 'rubocop-rspec', '2.25.0', require: false
+end
+
+group :development do
+  gem 'appraisal'
+  gem 'benchmark-ips'
+  gem 'benchmark-memory'
+  gem 'guard'
+  gem 'guard-rspec'
+  gem 'guard-rubocop'
+end
+
+group :test do
+  gem 'grape-entity', '~> 0.6', require: false
+  gem 'rack-jsonp', require: 'rack/jsonp'
+  gem 'rack-test', '< 2.1'
+  gem 'rspec', '< 4'
+  gem 'ruby-grape-danger', '~> 0.2.0', require: false
+  gem 'simplecov', '~> 0.21.2'
+  gem 'simplecov-lcov', '~> 0.8.0'
+  gem 'test-prof', require: false
+end
+
+platforms :jruby do
+  gem 'racc'
+end
+
+gemspec path: '../'

gemfiles/rack_1_0.gemfile

@@ -9,6 +9,7 @@ gem 'rack', '~> 1.0'
 group :development, :test do
   gem 'bundler'
   gem 'hashie'
+  gem 'dry-validation'
   gem 'rake'
   gem 'rubocop', '1.59.0', require: false
   gem 'rubocop-performance', '1.20.1', require: false

gemfiles/rack_2_0.gemfile

@@ -9,6 +9,7 @@ gem 'rack', '~> 2.0'
 group :development, :test do
   gem 'bundler'
   gem 'hashie'
+  gem 'dry-validation'
   gem 'rake'
   gem 'rubocop', '1.59.0', require: false
   gem 'rubocop-performance', '1.20.1', require: false

gemfiles/rack_3_0.gemfile

@@ -9,6 +9,7 @@ gem 'rack', '~> 3.0.0'
 group :development, :test do
   gem 'bundler'
   gem 'hashie'
+  gem 'dry-validation'
   gem 'rake'
   gem 'rubocop', '1.59.0', require: false
   gem 'rubocop-performance', '1.20.1', require: false

gemfiles/rack_edge.gemfile

@@ -9,6 +9,7 @@ gem 'rack', github: 'rack/rack'
 group :development, :test do
   gem 'bundler'
   gem 'hashie'
+  gem 'dry-validation'
   gem 'rake'
   gem 'rubocop', '1.59.0', require: false
   gem 'rubocop-performance', '1.20.1', require: false

gemfiles/rails_6_0.gemfile

@@ -9,6 +9,7 @@ gem 'rails', '~> 6.0.0'
 group :development, :test do
   gem 'bundler'
   gem 'hashie'
+  gem 'dry-validation'
   gem 'rake'
   gem 'rubocop', '1.59.0', require: false
   gem 'rubocop-performance', '1.20.1', require: false

gemfiles/rails_6_1.gemfile

@@ -9,6 +9,7 @@ gem 'rails', '~> 6.1'
 group :development, :test do
   gem 'bundler'
   gem 'hashie'
+  gem 'dry-validation'
   gem 'rake'
   gem 'rubocop', '1.59.0', require: false
   gem 'rubocop-performance', '1.20.1', require: false

gemfiles/rails_7_0.gemfile

@@ -9,6 +9,7 @@ gem 'rails', '~> 7.0.0'
 group :development, :test do
   gem 'bundler'
   gem 'hashie'
+  gem 'dry-validation'
   gem 'rake'
   gem 'rubocop', '1.59.0', require: false
   gem 'rubocop-performance', '1.20.1', require: false

gemfiles/rails_edge.gemfile

@@ -9,6 +9,7 @@ gem 'rails', github: 'rails/rails'
 group :development, :test do
   gem 'bundler'
   gem 'hashie'
+  gem 'dry-validation'
   gem 'rake'
   gem 'rubocop', '1.59.0', require: false
   gem 'rubocop-performance', '1.20.1', require: false

lib/grape.rb

@@ -249,6 +249,7 @@ module Validations
       autoload :SingleAttributeIterator
       autoload :Types
       autoload :ParamsScope
+      autoload :ContractScope
       autoload :ValidatorFactory
       autoload :Base, 'grape/validations/validators/base'
     end

lib/grape/dsl/inside_route.rb

@@ -31,11 +31,17 @@ def declared(passed_params, options = {}, declared_params = nil, params_nested_p
           options = options.reverse_merge(include_missing: true, include_parent_namespaces: true, evaluate_given: false)
           declared_params ||= optioned_declared_params(**options)
 
-          if passed_params.is_a?(Array)
-            declared_array(passed_params, options, declared_params, params_nested_path)
-          else
-            declared_hash(passed_params, options, declared_params, params_nested_path)
+          res = if passed_params.is_a?(Array)
+                  declared_array(passed_params, options, declared_params, params_nested_path)
+                else
+                  declared_hash(passed_params, options, declared_params, params_nested_path)
+                end
+
+          if (key_maps = namespace_stackable(:contract_key_map))
+            key_maps.each { |key_map| key_map.write(passed_params, res) }
           end
+
+          res
         end
 
         private

lib/grape/dsl/validations.rb

@@ -38,6 +38,19 @@ def reset_validations!
         def params(&block)
           Grape::Validations::ParamsScope.new(api: self, type: Hash, &block)
         end
+
+        # Declare the contract to be used for the endpoint's parameters.
+        # @param contract [Class<Dry::Validation::Contract> | Dry::Schema::Processor]
+        #   The contract or schema to be used for validation. Optional.
+        # @yield a block yielding a new instance of Dry::Schema::Params
+        #   subclass, allowing to define the schema inline. When the
+        #   +contract+ parameter is a schema, it will be used as a parent. Optional.
+        def contract(contract = nil, &block)
+          raise ArgumentError, 'Either contract or block must be provided' unless contract || block
+          raise ArgumentError, 'Cannot inherit from contract, only schema' if block && contract.respond_to?(:schema)
+
+          Grape::Validations::ContractScope.new(self, contract, &block)
+        end
       end
     end
   end

lib/grape/validations/contract_scope.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Grape
+  module Validations
+    class ContractScope
+      # Declare the contract to be used for the endpoint's parameters.
+      # @param api [API] the API endpoint to modify.
+      # @param contract the contract or schema to be used for validation. Optional.
+      # @yield a block yielding a new schema class. Optional.
+      def initialize(api, contract = nil, &block)
+        # When block is passed, the first arg is either schema or nil.
+        contract = Dry::Schema.Params(parent: contract, &block) if block
+
+        if contract.respond_to?(:schema)
+          # It's a Dry::Validation::Contract, then.
+          contract = contract.new
+          key_map = contract.schema.key_map
+        else
+          # Dry::Schema::Processor, hopefully.
+          key_map = contract.key_map
+        end
+
+        api.namespace_stackable(:contract_key_map, key_map)
+
+        validator_options = {
+          validator_class: Validator,
+          opts: { schema: contract }
+        }
+
+        api.namespace_stackable(:validations, validator_options)
+      end
+
+      class Validator
+        attr_reader :schema
+
+        def initialize(*_args, schema:)
+          @schema = schema
+        end
+
+        # Validates a given request.
+        # @param request [Grape::Request] the request currently being handled
+        # @raise [Grape::Exceptions::ValidationArrayErrors] if validation failed
+        # @return [void]
+        def validate(request)
+          res = schema.call(request.params)
+
+          if res.success?
+            request.params.deep_merge!(res.to_h)
+            return
+          end
+
+          errors = []
+
+          res.errors.messages.each do |message|
+            full_name = message.path.first.to_s
+
+            full_name += "[#{message.path[1..].join('][')}]" if message.path.size > 1
+
+            errors << Grape::Exceptions::Validation.new(params: [full_name], message: message.text)
+          end
+
+          raise Grape::Exceptions::ValidationArrayErrors.new(errors)
+        end
+
+        def fail_fast?
+          false
+        end
+      end
+    end
+  end
+end