Provide ability to restrict declared(params) to local endpoint

[myitcv]

#503 (which has been pulled) changes the default behaviour of declared(params) to return all params from the current endpoint and containing namespaces.

This PR provides the ability to restrict that to the local endpoint (effectively the previous default behaviour) via an option:

declared(params, restrict_local: true)

This is particularly useful for endpoints which create/update resources.

I think the current default (i.e. with #503 pulled) is correct. i.e. one should have to specify restrict_local to only consider params defined on the local/current endpoint, hence this PR. Arguably the ability to restrict should have been included in #503.

Thoughts?

I can updated the CHANGELOG if we are comfortable.

[dblock]

To keep a positive spirit,... okay, to keep things consistent with other options, I'd like that option to be a positive one. Instead of restrict_local I would make it include_some-good-name-here and default that to true.

[myitcv]

Quite understand the desire for consistency. How about:

declared(params, include_parent_namespaces: true)

Thinking being that 'parent' is more descriptive than 'containing'

include_parent_namespaces would be true by default, hence retaining the behaviour as committed in #503

Thoughts?

[dblock]

Are there any other kinds of namespaces? Otherwise maybe just include_namespaces? Otherwise yes.

[myitcv]

The only potential confusion is with namespace's which are defined in the same namespace as the calling endpoint: e.g

class MyAPI < Grape::API
  params do
    requires :id, type: String
  end
  namespace ':id' do

    params do
      requires :name, type: String
    end
    get do
      # ** CALL FROM HERE **
      declared(params)....
    end

    params do
      requires :age, type: Integer
    end
    namespace ':age' do

      # ...

    end
  end
end

Hence 'parent' captures every namespace that contains the current endpoint.

[dblock]

That makes sense. I'll take a PR with whichever.

[myitcv]

Ok, I've updated the commit to use include_parent_namespaces - this includes some further documentation changes to explain things a bit further.

Let me know if there's any further clarifications I can make

[myitcv]

@dblock - any update on this?

[dblock]

This looks good. Can you amend with a CHANGELOG entry, please? Thx.

[myitcv]

All done

[dblock]

Change the text from "should not include" to "does not include".

[dblock]

See my minor comment in spec, and please rebase this.

[myitcv]

All done (again!)

[dblock]

Merged via 3a55dc7 (slight change in the CHANGELOG wording).

[myitcv]

Awesome. Thanks