No documentation for creating associated record from grape entity documentation

[brahamshakti]

Hi I don't know how to create an associated record from grape entity for. eg. I have two model Event and Setting and their relation is like event has_one: :setting and setting belongs_to: :event . Now while creating event using

 desc 'Create an event.' ,{
     params: Entities::EventEntity.documentation, type: :create
  }

My entity class is

module Entities
  class EventEntity < Grape::Entity
    expose :id
    expose :name, documentation: { type: String, desc: "Event name", required: true}
    expose :setting, using: Entities::EventSettingEntity
  end
end

and event_setting_entity is

module Entities
  class EventSettingEntity < Grape::Entity
    expose :id, :event_id
    expose :type, documentation: { type: String, desc: "Type" }
  end
end

I am able to create event using documentation but for setting how do I show field for setting. There is no documentation provide for this. Help me please. Thanks

[sunnyrjuneja]

I think @brahamshakti brings up a really valid point. Where are the documentation options documented? In the README, neither required or example ever show up. The options for Type never appear either.

I'm happy to send a PR to update the documentation but where can I learn this in the code?

[marshall-lee]

@whatasunnyday

https://github.com/ruby-grape/grape#describing-methods

[sunnyrjuneja]

Thanks for that @marshall-lee.

[sunnyrjuneja]

Hey @marshall-lee thanks for the link but I think you may have misunderstood me. That's explains the documentation for the routes but not entities.

My complaint was that the examples in grape-entity, it shows documentation for type and desc. Like so:

expose :text, documentation: { type: "String", desc: "Status update text." }

However, neither required or example show up in the README and the values for type don't appear (String, Integer, not sure what else). I don't think there are more options then required or example but I'm not 100% sure. I have no idea how type works. If you can point me to some code, I'm happy to try to improve the README myself.

Also, follow up question based on your link:

Grape README:

success: (former entity) The Entity to be used to present by default this route
failure: (former http_codes) A definition of the used failure HTTP Codes and Entities

grape-swagger README:

desc 'Get all kittens!', {
  :hidden => true,
  :is_array => true,
  :nickname => 'getKittens',
  :entity => Entities::Kitten, # use entity instead of success
  :http_codes => [[401, 'KittenBitesError', Entities::BadKitten]]  # use http_codes instead of failure
  }

Why does grape-swagger require entity/http-codes instead of success/failure?

[marshall-lee]

@whatasunnyday

:documentation is just an arbitrary hash that you can associate with entity fields (exposures). This is why you couldn't find anything related in the code of grape-entity. grape-entity is agnostic about it. But I agree, :documentation should be documented 😄 in grape-entity's README.

The meaning to this hash give the projects that use it. grape-swagger, for instance.

BTW I don't know how Grape itself parses entity documentation too. I know how grape-swagger handles it, but don't know about grape.

So if you want to contribute you should search for answers in grape and grape-swagger.

[brahamshakti]

Hi I don't know whether you understand my question or not. Two months ago I asked you a question like how do i send parameters for associations. If I write this

desc 'Create an event.' ,{
  params: Entities::EventEntity.documentation
}

Then expose :setting, using: Entities::EventSettingEntity this does not work because I am not able to figure out the syntax for writing documentation for showing setting field for my above example.

Please try to complete the syntax so that association fields are visible

expose :setting, using: Entities::EventSettingEntity, documentation: { what to do here......}

[mia-n]

8 Years later I was hoping to do exactly this.

expose :setting, using: Entities::EventSettingEntity, documentation: { what to do here......}

Is this supported? I'm not sure using entities buys me anything if it doesn't handle request serialization as well as responses.

[LeFnord]

it depends on other gems you want to use with
if you plan to use it togehter with grape-swagger, have a look here → grape-swagger#using-grape-entities