Api description success entity status code

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.

Start by tracing the desc block and its existing success and failure declarations, then compare them with the request's status call. Done requires a decided syntax for documenting custom success status codes and agreement on whether the declared status should also change response behavior.