Grape Swagger describe JSON body

Question

I'm sending JSON request for most of the POST requests and I embed the JSON in the request body. How can I describe this using grape swagger ?

Answer 1

Adding descriptions for params is easy (I assume that is what you mean by "How can I describe this using grape swagger ?"). Ivan shows you how to create the params blocks with a Hash or Array but to describe them with Grape Swagger you need to add a description parameter to the requires or optional in the params block.

class API::Users < Grape::API
  resource 'user' do
    desc 'Create a new user'
    params do 
      requires :user, type: Hash, desc: 'user object to create' do 
        requires :first_name, type: String, desc: 'First name of user'
        requires :last_name, type: String, desc: 'Last name of user'
      end
    end
    post do 
      # do work here
    end
  end
end

Both the desc before the endpoint and the desc keys in the hash sent to requires will be picked up by Grape Swagger and included in the automatic documentation.

Answer 2

You can use an Array or Hash to describe

params do
 optional :preferences, type: Array do
  requires :key
  requires :value
 end

 requires :name, type: Hash do
  requires :first_name
  requires :last_name
 end
end

Array when you need to save has_many objects. Hash when you need to save just an object.

Ex:

params do
  requires :post, type: Hash do
    requires :title
    requires :description
    optional :images_attributes, type: Array
  end
end