Apidoc: How to describe complex (nested hash) parameters?

[dvv]

Hello,

I would like to document a bunch of methods which all take nested hashes as the single parameter and return a nested hash as well. (The rationale of such a design is that prescribed language of choice is PHP which does not allow for named arguments).

E.g. (expressed in loose JSON)

{
  "foo": [
    {"bar": 1, "baz": "quux"}, // <--- can not find way to document these ones
    {"bar": 2, "baz": "quuz"}
  ]
}

I could not find a way to properly denote in-depth keys. Tried what came to mind quickly -- both dotted notation for field names and groups as artificial hash but without success.

TIA,
--Vladimir

[rcrooks]

@dvv here's an example from our docs (success params):

* @apiSuccess (Response Fields) {Object} images map of image maps
* @apiSuccess (Response Fields) {Object} images.poster map of poster properties
* @apiSuccess (Response Fields) {String} images.poster.asset_id asset id for the poster
* @apiSuccess (Response Fields) {Object[]} images.poster.sources array of poster source maps
* @apiSuccess (Response Fields) {Url} images.poster.sources.src URL for a poster source image
* @apiSuccess (Response Fields) {Url} images.poster.src URL for the default poster source image
* @apiSuccess (Response Fields) {Object} images.thumbnail map of thumbnail properties
* @apiSuccess (Response Fields) {String} images.thumbnail.asset_id asset id for the thumbnail
* @apiSuccess (Response Fields) {Object[]} images.thumbnail.sources array of thumbnail source maps
* @apiSuccess (Response Fields) {Url} images.thumbnail.sources.src URL for a thumbnail source image
* @apiSuccess (Response Fields) {Url} images.thumbnail.src URL for the default thumbnail source image

I think that will give you the idea.

You can see what the output looks like here (mildly customized template): http://docs.brightcove.com/en/video-cloud/cms-api/references/cms-api/versions/v1/index.html#api-Video-Get_Videos

[dvv]

I see. Thank you.

[ashishsingla89]

Hi @rcrooks please help me for this senario -
{"user"=>{"token"=>"CAANwSAlT6", "email"=>"[email protected]"}}

I want to create document for above nested hashes.User as a key and it has further key value pairs.

[rcrooks]

@ashishsingla89 it should look like this:

* @apiParam (Request Fields) {Object} user 
* @apiParam (Request Fields) {String} user.token
* @apiParam (Request Fields) {String} user.email

[ashishsingla89]

Hi, @rcrooks thanks for the reply.
I have tried in the same way but it creates request like this -
{"user"=>"", "user.token"=>"GJHGJ67KJL", "user.email"=>"[email protected]"}
but it should be like
{"user"=>{"token"=>"GJHGJ67KJL", "email"=>"[email protected]"}}

In my doc i have written below params :-

• @apiSampleRequest /api/v1/sessions
• @apiName Login
• @apiGroup User
• @apiDescription User can Login its account.
• @apiParam (User) {Object} user User attributes
• @apiParam (User) {String} user.token Provide the user token
• @apiParam (User) {String} [user.email] Provide the user email

Please correct me if i am adding wrong parameters

[rcrooks]

Ah, yes, anonymous nested objects are a challenge that I haven't been able to solve - and I can't use the try-it feature of APIDOC for other reasons, so I haven't had to worry about that. Sorry.

[ashishsingla89]

@rcrooks ok, thank you.

[dvv]

Wonder how to fill array fields when filling forms for using sampleUrl?