Proposal: new desc dsl with a block instead of option Hash

[dspaeth-faber]

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

  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.

[dblock]

Sorry for being late at this.

Today we have things like desc and params at the same level, so this would change pretty drastically. Do you think we are going to deprecate the old behavior. And if not, why do we want a block this way and not continue adding decorators like params, which personally doesn't seem crazy to me at all.

[dspaeth-faber]

params is taken from the docs.

The example within the docs is the following:

desc 'Statuses index', {
      params: API::Entities::Status.documentation
}

It should not replace the "other" params method.

I did create this PR because the hash syntax like this:

desc "some descs",
         entity: API::Entities::Entity,
         named: 'a name',
         headers :[XAuthToken: {
              description: 'Valdates your identity',
              required: true
            }
get nil, http_codes: [
          [401, 'Unauthorized', API::Entities::BaseError],
          [404, 'not found', API::Entities::Error]

] do

can't be read so smoothly in my point of view.
Furthor more without the hash syntax new keys like headers
can't be so easaly included and grape will be the master over all
possible keys.

[dblock]

Yeah, I think I agree. Why would this not let you set anything unknown via a method_missing? In our API we set all kinds of things and examine them at runtime.

[dspaeth-faber]

What I mean is this:

desc 'Statuses index', {
      params: API::Entities::Status.documentation,
      my_param1: 'value',
      my_param1: 'value2'
}

Every one can introduce new paramters like grape-swagger did with headers and
grape does not know this parameter. When grape changes some thing within the documentation handling such code can break and finger pointing starts.

[dblock]

I am not in love with the new_desc_config name. Maybe just create?

[dblock]

I am OK with this. I think it might need some README updates, especially ensuring that all those hard-coded parameters are documented.

[dspaeth-faber]

@dblock I think I did address all your hints. If some thing is missing drop a line.

[dblock]

I'm merging this.

[dspaeth-faber]

Thanks :)

[antek-drzewiecki]

@dspaeth-faber i've got a question. When using grape-swagger, if success parameter expects an entity, how do you document HTTP Status codes and descriptions for success entities? For example a get request would normally result in an 200 status code, and a post would result in a 201. Is it something that grape-swagger will have to find out?

[dspaeth-faber]

@antek-drzewiecki sorry I had have some days off. I will turn to this in the next days.

regards
dieter

[dspaeth-faber]

how do you document HTTP Status codes and descriptions for success entities

As far as I know there is no official way to document success http code
here http://petstore.swagger.wordnik.com/#!/store/placeOrder I haven't found one either

[antek-drzewiecki]

Hi @dspaeth-faber, thanks for replying. You are correct, I could not find a official way to document success codes. Given the example of the placeOrder endpoint. My preference is to add a 201 'Order created' OrderEntity above the 400 'Invalid ID supplied'. Since it is not always trivial that the API returns a 200 status code on a success. In my opinion Response Messages should also contain information about success actions.

My preference is to document errors and success codes the following way:

desc 'The description' do
            detail 'more details'
            params API::Entities::Status.documentation
            success [201,'Tweet created', Tweet::Entity]
            failure [[401, 'Unauthorized', "Entities::Error"]]
            named 'My named route'

Which should responseMessage array with both codes.

A workaround for me could be to add success entity to the failure codes.

[dspaeth-faber]

Maybe the better way is to first create an issue within swagger-spec how this guys want to handle success codes. When they have made a commitment we can add it to grape.

As long as this does not happen we can missuse maybe the notesproperty. But I'm not sure if it is supported by grape-swagger.

[antek-drzewiecki]

Good point @dspaeth-faber . Ill make a issue there.

Currently swagger-spec has a way to define authorization ( operations object ) attributes on an endpoint level. How should we handle the authorization? Im getting the feeling this is not really an issue of Grape. Tough my gem WineBouncer, used the hash for defining endpoint authorization, which grape-swagger parses into their authorisations array. It would be nice to define endpoint protection with belonging scopes.

[dspaeth-faber]

The new block syntax does not know anything of authorizations so it want work with the block syntax.

I think the authorization section within the documentation for swagger should some how be generated from the auth stanza.

auth :oauth, { ... } do |...|

end