Share desc and type across Grape and GrapeEntity

[pinkynrg]

What I'm trying to do it to re-use type and description across grape and grape-entity.

In the documentation I read the following:

You can use entity documentation directly in the params block with using: Entity.documentation.

module API
  class Statuses < Grape::API
    version 'v1'

    desc 'Create a status'
    params do
      requires :all, except: [:ip], using: API::Entities::Status.documentation.except(:id)
    end
    post '/status' do
      Status.create! params
    end
  end
end

This allows me to use field description and field type from the documentation defined in the Grape Entity. Whenever I define an API that requires only 1 field of the ones defined in the Grape Entity, I need to do something like the following (which I find kind of dirty):

given:

module Entities
  class Host < Grape::Entity
    expose :mac_address, documentation: { type: String, desc: "The mac address of the host" }
  end
end

I can do:

params do
  requires :mac_address, type: V1::Entities::Host.documentation[:mac_address][:type], desc: V1::Entities::Host.documentation[:mac_address][:desc]
end

I don't like the above solution mainly for 2 reasons:

1. I don't like to use the field "type" of an helper that was meant to support documentation generation.
2. It is cumbersome.

Is there a better way to share type and description across the 2 gems?

[dblock]

I don't think there's a better way today. What do you think you'd like to write (as a user)?

[pinkynrg]

The main reason I would like to share type/description is because I'm using grape-swagger which gets the description both in the attributes of the entity, and the parameters defined for every API endpoint.

As mentioned above I don't like to use grade entity type/description as source of truth since it is in a hash used only for documentation and unfortunately I cannot get field's type/description from the API endpoint (to populate grape entity fields).

Maybe it would be nice for grape-swagger to get both type and description from grape entity unless param type/description are defined inside the API endpoint? This would become a grape-swagger issues.

[LeFnord]

there is one other way, use the params key of the describe block …

desc 'some description',
  params: Entity.documentation

without the params block, downcase of it is, with that all the parameter niceties (validation, etc.) of grape are lost

best thing IMHO would be, that parameters which are described in the desc method/block would be handled in the same manner as which one definied in the params block

@dblock what did you think?

[pinkynrg]

Maybe what I requested above is a little to magical and to coupled to grape-swagger usage. Another dreamy way of doing it would be something like:

desc 'some api for my Entity resource', {
   http_codes: [...]
}
params {
  requires some_param, type: String, ...
  optional some_other_param, type: Integer, ...
}, documentation: V1::Entities::MyEntity.documentation

documentation: V1::Entities::Host.documentation be used to populate the documentation of some_param, some_other_param.

I don't even know if this is possible using ruby though.

What do you guys think?

[dblock]

Reversing, and with a block it's possible, so desc ... do and params documentation: ... do

[pinkynrg]

Whenever I have time I will look into it and see what I can do

[run27017]

Hey, I am making new framework to enhance this, which is still based on grape framework now. You can see what I upgrade from my repository:

https://github.com/run27017/grape-group#integration-of-parameters-and-entities