Fix array of entities with nested entities

[jdmurphy]

Similar in some respects to grape-swagger-rails #74 and #482, I found that when using body params in PUT and POST, an array of entities with a nested entity does not generate valid OpenAPI specs due to an issue where the :items key is removed after only looking at :type and :format keys when a $ref key is also possible.

So for:

        params do
          requires :spline, type: Hash, documentation: {param_type: 'body'} do
            requires :x, type: Numeric
            requires :y, type: Numeric
            requires :sub_splines, type: Array do
              requires :all, using: Api::Entities::SubSplines.documentation
            end
          end
          optional :reticulated, type: Boolean, default: true, desc: 'True if the spline is reticulated.'
        end

When the Entities are

class SubSubSplines < Grape::Entity
  expose :id, documentation: { type: Integer, desc: 'identity of a resource' }

  private

  def path
    "/#{object.class.name.demodulize.to_s.underscore}/#{object.id}"
  end
end

class SubSplines < Grape::Entity
  expose :id, documentation: { type: Integer, desc: 'identity of a resource' }
  expose :sub_sub_splines, documentation: { type: Api::Entities::SubSubSplines, desc: 'bar' }

  private

  def path
    "/#{object.class.name.demodulize.to_s.underscore}/#{object.id}"
  end
end

class Splines < Grape::Entity
  expose :id, documentation: { type: Integer, desc: 'identity of a resource' }
  expose :x, documentation: { type: Float, desc: 'x-value' }
  expose :y, documentation: { type: Float, desc: 'y-value' }
  expose :path, documentation: { type: String, desc: 'the requested resource' }
  expose :sub_splines, documentation: { type: Api::Entities::SubSplines, desc: 'foo', is_array: true }

  private

  def path
    "/#{object.class.name.demodulize.to_s.underscore}/#{object.id}"
  end
end

the generated, invalid OpenAPI spec for the params looks like (note that sub_sub_splines has a type of array and items is null):

"putSplines":{  
   ...
            "sub_splines":{  
               "type":"array",
               "items":{  
                  "type":"object",
                  "properties":{  
                     "id":{  
                        "type":"integer",
                        "format":"int32",
                        "description":"identity of a resource"
                     },
                     "sub_sub_splines":{  
                        "type":"array",
                        "description":"bar",
                        "items":null
                     }
                  },
                  "required":[  
                     "id",
                     "sub_sub_splines"
                  ]
               }
   ...
   },
   "description":"Update a spline."
}

With my fix, valid OpenAPI spec like the following is created:

"sub_splines":{  
   "type":"array",
   "items":{  
      "type":"object",
      "properties":{  
         "id":{  
            "type":"integer",
            "format":"int32",
            "description":"identity of a resource"
         },
         "sub_sub_splines":{  
            "type":"object",
            "description":"bar",
            "items":{  
               "$ref":"#/definitions/SubSubSplines"
            }
         }
      },
      "required":[  
         "id",
         "sub_sub_splines"
      ]
   }
}

[coveralls]

Coverage increased (+2.3%) to 99.535% when pulling 2689a8d on jdmurphy:array_of_nested_entities into c00c5b4 on ruby-grape:master.

[LeFnord]

thanks @jdmurphy … a very welcome fix 😄