Feature: add group attributes for parameter definitions

[304]

It is a proposal with a working prototype for a group attributes feature. If it makes sense then I will continue working on this PR. Your feedback is welcome.

I was looking into this issue (#1482) recently. I think the presented use case is common for complex APIs schemas. Currently, if I want to apply the same validator (or the same type) for a several endpoint attributes, then I have to define it for every parameter.

What if we introduce a way of defining common parameter settings? Something like Rails conditional validations.

For example, this parameters definition:

params do
  requires :first_name, type: String, allow_blank: false
  requires :last_name, type: String, allow_blank: false
end

can be replaced with

params(with: { type: String, allow_blank: false }) do
  requires :first_name
  requires :last_name
end

It is also possible to extract group attributes into a class method and use it instead of default params in your code. It should provide the solution for the problem from #1482.

class MyAPI < Grape::API do
  def self.not_blank_params(&block)
    params(with: { allow_blank: false }, &block)
  end

  not_blank_params do
    requires :first_name # This param won't accept blank lines 
    requires :last_name, allow_blank: true # This param *will* accept blank lines. 
  end
end

/cc @dblock

[rnubel]

I think the use case where all parameters for an endpoint share the same options is pretty rare; even if your initial endpoint has only homogenous params, eventually you'll want to add an extra param of a different type and be forced to undo all the shared options. However, like you point out, having a group of parameters with shared options is very common. What about a solution which introduces a new method within the params DSL? Something like this:

params do
  with(type: String, allow_blank: false) do
    requires :first_name
    requires :last_name
  end

  requires :age, type: Integer, allow_blank: true
end

[dblock]

Thanks @304, this is great. I think @rnubel's suggestion is spot on and is even better, since this gives us a proper DSL to deal with within params and something much more extensible for the future. I'd definitely take that PR.

[dgasper]

@rnubel I guess this should already be possible like this:

params do
  requires :first_name, :last_name, type: String, allow_blank: false
  requires :age, type: Integer, allow_blank: true
end

[jlfaber]

You can use an array of attribute names rather than a single one to define a bunch of identical attributes, right?

params do
  requires %i(first_name last_name), type: String, allow_blank: false
end

One could also use a params helper to dynamically specify the name(s) of attrs that need a specific validation.

helpers do
  params :name do |options|
    optional options[:attr], type: String, allow_blank: false
  end
end

params do
  use :name, attr: :first_name
  use :name, attr: :last_name
end

[304]

Thank you for the feedback! I like @rnubel's suggestion too. I think it is better to have it this way than as a part of params method. I will try to implement it and I will update this PR when I have something to show.

[304]

It is ready. I've added a new method with to Grape DSL. It allows to extract and group common options for a list of parameters. The documentation was also updated. Can you please take a look?

/cc @dblock

[dblock]

I'm going to merge this. Seems like a sensible add-on and doesn't hurt at the very least. If anyone hates it or thinks it can be improved further, speak up so we can iterate before the next release.