grape
grape copied to clipboard
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.
@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 }
]
Maybe add a status DSL is more convenient, read my doc:
https://github.com/run27017/grape-group#the-response-entity