Objects with dynamic contents

[gsbucks]

Hi Matt,

I was wondering if you had thought about supporting response objects/elements where the names and types of the contained attributes are not the same for each response.

For example, we have an API which returns an object very much based on the attributes present on a model which is versioned using the paper_trail gem. Each object has a changeset, which only contains those fields which were altered by the user, and an array of the previous and new values { field: [old_value, new_value] }.

Since the specific contents are variable, they can't be defined using the DSL and still pass a test using the JSONResponseVerification module as far as I know. I'd like to be able to do something like the following...

service.response do |response|
    response.array :form_changes do |changes|
      changes.integer  :id
      changes.integer  :person_id
      changes.element( { name: :changeset } ) do |set|
         set.attribute({ item_field: :array, doc: 'There will be one of more of these fields, etc....' })
      end
  end
end

Which would generate documentation like the following..

Response description PATIENT_FORM_CHANGES of type ARRAY

• PROPERTIES OF EACH ARRAY ITEM:
  • ID of type INTEGER
  • PERSON_ID of type INTEGER
  • CHANGESET of type OBJECT
  • PROPERTIES:
    • ITEM_FIELD of type ARRAY (There will be one of more of these fields, etc....)

However, be able to mark the changeset object as dynamic, or something along those lines such that it's contents are either ignored by the response verification, or is only verified that it contains key-value pairs and nothing more specific.

Basically we'd like a way to have attributes which show up in the generated documentation, but which are not deeply verified in the tests.

So the main questions are: is this already possible and I just can't recognize how to do it, or have you considered this yet as something that should be added to this library?

Thanks a lot

[mattetti]

This is an interesting problem that I "solved" by simply adding the :null => true option. So if a response attribute depends on the input, I add all possible response attributes and mark the optional as nullable and explain in the documentation when they are available.

I'm absolutely open to something more flexible, maybe an enum element type might work tho. I'm absolutely open to extending the DSL to support these use cases.

[gsbucks]

Thanks, Matt. I think using :null => true will work well enough for what we need right now. If I find out later we need it to be more flexible I'll come back with a pull request you can look at.