Api description success entity status code

[antek-drzewiecki]

Hello,

I wanted to discuss and optional pull request about http status codes. Mainly because I often notice success status codes are often not properly documented in most tooling. This would also be an awesome feature for documentation tools.

Grape returns a standard 200 on get, put, patch, delete requests and a 201 on post requests. This is great for me. Tough you can override status codes on successful requests. Shouldn't we be able to describe it?

For example someone wants:

post do
  some_method
  status 202
end

Maybe we can introduce a status code in the description like:

desc 'Some method.' do
  success API::Entities::Entity
  status_code 202
  failure [[401, 'Unauthorized', 'Entities::Error']]
end
post do
  some_method
  status 202
end

Or a more failure like syntax:

desc 'Some method.' do
  success [202, 'Ok', API::Entities::Entity]
  failure [[401, 'Unauthorized', 'Entities::Error']]
end
post do
  some_method
  status 202
end

Finally, we can even refactor out the status in the post body to automatically return the defined success status code.

[yuryroot]

@antek-drzewiecki please try to use something like following code:

desc 'Some method.', http_codes: [
  { code: 202, model: API::Entities::Entity },
  { code: 401, model: API::Entities::Error }
]

[run27017]

Maybe add a status DSL is more convenient, read my doc:

https://github.com/run27017/grape-group#the-response-entity