Document root namespace

[migmartri]

Hi,

For my endpoints, I wrap my response in a data namespace (using root keyword) in a similar way as shown in the example below.

The problem is that it seems that there is not a way to document that behavior using desc.success or failure.

Is there any way to tell grape-swagger that I want my success model under a data root without adding that namespace in the entity itself?

Thanks,
Miguel.

resource 'cats' do
  desc 'Get a list of cats.' do
    success model: API::V1::Entities::Cat
  end      
  
  get '/' do
    # some code to get @cat
    present @cat, with: API::V1::Entities::Cat, root: :data
  end
end

[migmartri]

Apparently this feature is not supported at the response level by Swagger itself yet so I am afraid that the only way we could solve this would be to create a wrapping entity with the root key that refs the original entity.

[kzaitsev]

hello, @migmartri as i know, it's not possible out of box, but you can write custom data-wrapper and model parser for this.

[kzaitsev]

For example:

# Wrapper
class DataWrapper
  attr_reader :model
  attr_reader :key
  attr_reader :is_array
  attr_reader :wrapper_name

  def initialize(model, wrapper_name: nil, key: :data, is_array: false)
    @model = model
    @wrapper_name = wrapper_name
    @key = key
    @is_array = is_array
  end

  def ancestors
    [DataWrapper]
  end

  def to_s
    wrapper_name ? wrapper_name : "data_wrapper_#{object_id}"
  end
end

# Parser
class DataWrapperParser
  attr_reader :wrapper
  attr_reader :endpoint

  def initialize(wrapper, endpoint)
    @wrapper = wrapper
    @endpoint = endpoint
  end

  def call
    memo = {}

    name = endpoint.send(:expose_params_from_model, wrapper.model)

    memo[wrapper.key] = if wrapper.is_array
                          {
                            type: :array,
                            items: {
                              '$ref' => "#/definitions/#{name}"
                            }
                          }
                        else
                          {
                            type: :object,
                            '$ref' => "#/definitions/#{name}"
                          }
                        end
    memo
  end
end

# Add model parser to grape-swagger
GrapeSwagger.model_parsers.register(DataWrapperParser, DataWrapper)

# In api
desc 'Get all splines',
  http_codes: [
    { code: 200, message: 'get Splines', model: DataWrapper.new(Api::Entities::Splines, key: :items, is_array: true) },
    { code: 422, message: 'SplinesOutError' }
]
get do
  present :items, @@splines, with: Entities::Splines
end

is_array: true - array

is_array: false - object

[LeFnord]

@Bugagazavr … thanks, this explanation is very helpful 👍

[migmartri]

@Bugagazavr thank you! This is gold :)