Document queryParameters as nested maps


#1

Hi.

I am trying to document our REST APIs written in Rails.
And I am having a hard time trying to figure out how to best represent the request body in nested attributes.
For example, when I am creating a record, this is the sort of parameters I am sending to the endpoint.

"documents":{
  "attachment_attributes":{  
      "0":{
          "attachment_id":1,
          "position":1,
          "type":"file"
      },
      "1":{
          "attachment_id":2,
          "position":2,
          "type":"url"
      }
  }
}

These nested attributes parameters could contain no or multiple values.
The key of each nested_attribute value, in this case “0” and “1” are meant to be unique ids.
And the value of each nested attribute correspond to another map object, where the keys are largely the same in the same nested attribute type.

What I think I need, is almost a queryParameters of type “object”, that has a value that could almost be an object and is able to repeat.
Not too dissimilar from how JSON schema handles its map objects.

Thanks for reading,

Jimmy


#2

I will bump this question. How to document post body request? Documentation mention only string, number, integer, date, boolean and file named parameter types. How to document maps and arrays? JSON schema is only option?


#3

I am a little confused by the OOP and the bump… as far as I know, in RAML, you specify a resource, then the body: tag, then below it the example and schema for each media type represented. So each media type can have it’s own schema and example associated with it. So in the case of the OP, you would use JSON Schema to document the entity body for the request, and provide an example of JSON that shows how it would be composed. Is that not sufficient?