Ability to set description to whole entity

[Kukunin]

It seems there is no way to set global description for the whole Entity. If use grape-swagger-entity, it takes entity definition outside from resource, which I think is incorrect.

{  
   "definitions":{  
      "User":{  
         "type":"object",
         "properties":{  
            "username":{  
               "type":"string"
            }
         },
         "required":[  
            "username"
         ],
         "description":"Create a token from email/password pair"
      }
   }
}

This description seems being used nowhere, but it can be used as description on resource response section, when you set desc "Retrieve information about the signed user", entity: Entities::User

"responses":{"200":{"description":"User entity","schema":{"$ref":"#/definitions/User"}}

instead of

"responses":{"200":{"description":"Retrieve information about the signed user","schema":{"$ref":"#/definitions/User"}}

[viren140290]

I have a similar issue in one of the projects that I am working on. Swagger will not accept any other fields at the same level as $ref

testField:
  $ref: '#/definitions/referenceField'
  description: Something something

So I will need to move the description to the entity where referenceField is defined. However I could not find a way to apply documentation to the whole entity.

params :example do
  optional :testField, type: Hash, using: Test::ReferenceField.documentation
end

# frozen_string_literal: true

require 'grape-entity'

module Test
  class ReferenceField < Grape::Entity
    with_options(expose_nil: false) do
      expose :field,
             documentation: {
               type: String,
               desc: 'Example description',
               allow_blank: false,
             }
    end
  end
end

How can we add description for the RefernceField swagger model?

[gen0cide]

Bumping this. Anyway this could get fixed? It causes problems downstream in grape-swagger-entity when generating Swagger models.