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

@@ -228,7 +228,7 @@ RSpec/ExpectInHook:
     - 'spec/grape/api_spec.rb'
     - 'spec/grape/validations/validators/values_spec.rb'
 
-# Offense count: 47
+# Offense count: 48
 # Configuration parameters: Include, CustomTransform, IgnoreMethods, SpecSuffixOnly.
 # Include: **/*_spec*rb*, **/spec/**/*
 RSpec/FilePath:
@@ -278,6 +278,7 @@ RSpec/FilePath:
     - 'spec/integration/eager_load/eager_load_spec.rb'
     - 'spec/integration/multi_json/json_spec.rb'
     - 'spec/integration/multi_xml/xml_spec.rb'
+    - 'spec/integration/no_dry_validation/no_dry_validation_spec.rb'
     - 'spec/integration/rack/v2/headers_spec.rb'
     - 'spec/integration/rack/v3/headers_spec.rb'
 
@@ -341,7 +342,7 @@ RSpec/MissingExampleGroupArgument:
   Exclude:
     - 'spec/grape/middleware/exception_spec.rb'
 
-# Offense count: 788
+# Offense count: 804
 # Configuration parameters: Max.
 RSpec/MultipleExpectations:
   Exclude:
@@ -392,6 +393,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'
@@ -411,6 +413,7 @@ RSpec/MultipleExpectations:
     - 'spec/grape/validations/validators/same_as_spec.rb'
     - 'spec/grape/validations/validators/values_spec.rb'
     - 'spec/grape/validations_spec.rb'
+    - 'spec/integration/no_dry_validation/no_dry_validation_spec.rb'
     - 'spec/shared/versioning_examples.rb'
 
 # Offense count: 38
@@ -557,7 +560,7 @@ RSpec/ScatteredSetup:
     - 'spec/grape/util/inheritable_setting_spec.rb'
     - 'spec/grape/validations_spec.rb'
 
-# Offense count: 47
+# Offense count: 48
 # Configuration parameters: Include, CustomTransform, IgnoreMethods, IgnoreMetadata.
 # Include: **/*_spec.rb
 RSpec/SpecFilePathFormat:
@@ -608,6 +611,7 @@ RSpec/SpecFilePathFormat:
     - 'spec/integration/eager_load/eager_load_spec.rb'
     - 'spec/integration/multi_json/json_spec.rb'
     - 'spec/integration/multi_xml/xml_spec.rb'
+    - 'spec/integration/no_dry_validation/no_dry_validation_spec.rb'
     - 'spec/integration/rack/v2/headers_spec.rb'
     - 'spec/integration/rack/v3/headers_spec.rb'
 

Appraisals

@@ -1,19 +1,28 @@
 # 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-7-1' do
+  gem 'rails', '~> 7.1.0'
 end
 
 appraise 'rails-edge' do
@@ -32,14 +41,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

@@ -8,6 +8,7 @@ gemspec
 
 group :development, :test do
   gem 'bundler'
+  gem 'dry-validation'
   gem 'hashie'
   gem 'rake'
   gem 'rubocop', '1.59.0', 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,40 @@ 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
+CreateOrdersSchema = Dry::Schema.Params do
+  required(:orders).array(:hash) do
+    required(:name).filled(:string)
+    optional(:volume).maybe(:integer, lt?: 9)
+  end
+end
+
+# ...
+
+contract CreateOrdersSchema
+```
+
+or with a block, using the [schema definition syntax](https://dry-rb.org/gems/dry-schema/1.13/#quick-start):
+
+```rb
+contract do
+  required(:orders).array(:hash) 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.
+
+The `params` and `contract` declarations can also be used together in the same API, e.g. to describe different parts of a nested namespace for an endpoint.
+
 ## Headers
 
 ### Request

gemfiles/multi_json.gemfile

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

gemfiles/multi_xml.gemfile

@@ -8,6 +8,7 @@ gem 'multi_xml', require: 'multi_xml'
 
 group :development, :test do
   gem 'bundler'
+  gem 'dry-validation'
   gem 'hashie'
   gem 'rake'
   gem 'rubocop', '1.59.0', 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

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

gemfiles/rack_2_0.gemfile

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

gemfiles/rack_3_0.gemfile

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

gemfiles/rack_edge.gemfile

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

gemfiles/rails_6_0.gemfile

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

gemfiles/rails_6_1.gemfile

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

gemfiles/rails_7_0.gemfile

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

gemfiles/rails_7_1.gemfile

@@ -5,10 +5,10 @@
 source 'https://rubygems.org'
 
 gem 'rails', '~> 7.1.0'
-gem 'tzinfo-data', require: false
 
 group :development, :test do
   gem 'bundler'
+  gem 'dry-validation'
   gem 'hashie'
   gem 'rake'
   gem 'rubocop', '1.59.0', require: false

gemfiles/rails_edge.gemfile

@@ -8,6 +8,7 @@ gem 'rails', github: 'rails/rails'
 
 group :development, :test do
   gem 'bundler'
+  gem 'dry-validation'
   gem 'hashie'
   gem 'rake'
   gem 'rubocop', '1.59.0', 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