intridea/grape — pull request #757 by dspaeth-faber (2014-09-17 10:56:47+00:00)
Title: Proposal: new desc dsl with a block instead of option Hash

Like @mbleigh suggest in #620 I like to introduce a DSL like for `desc`:

```ruby
Class API < Grape::API
...
desc 'The description' do
detail 'more details'
params API::Entities::Status.documentation
success Tweet::Entity
failure [[401, 'Unauthorized', "Entities::Error"]]
named 'My named route'
headers [XAuthToken: {
description: 'Valdates your identity',
required: true
},
XOptionalHeader: {
description: 'Not really needed',
required: false
}
]
end
...
end
```

with this PR.

It's not complete like it was discussed within #620, but it's like every time a starting point.

Furthor more with this PR Options are strictly checked within Grape and cant be missused
like discussed here a little tim-vandecasteele/grape-swagger#49. So that grape will be the master.