Restler: Complex Object Types as Parameters

Question

Hello Restler friends,

I'm currently trying to switch to Restler as our main Rest-Framework. What really motivated my decision was the swagger compliance. I find it quite important to have a nice autogenerated documentation for an ongrowing system.

So, my problem is that I can't seem to find a way to use "complex objects" as post parameters as specified in swagger here : https://github.com/wordnik/swagger-core/wiki/Parameters.

Sure you could just retrieve everything from the "post assoc array" and then validate against the objects structures, but this would not be documented and the client would not know what structures are expected from him. Consequently I would have to write a spec. by hand...

Example :

/**
 * Create a new Account, based on the structure of the Account Object
 *
 * @param Account $account {@from body}
 *
 * @return string
 *
 */
protected function post(Account $account){...}

This would simply be put as an undefined "Object" in the resource.json and not as a "complex type" linked to the Account object (this is perfectly working for returned objects by the way)

Resource.json

"parameters": [
    {
    "name": "REQUEST_BODY",
    "description": "Paste JSON data here with the following property.<hr/><mark>account</mark> <i>(required)</i>: add <mark>@param {type} $account {comment}</mark> to describe here",
    "paramType": "body",
    "required": true,
    "allowMultiple": false,
    "dataType": "Object",
    "defaultValue": "{\n    \"account\": \"\"\n}"
    }
    ],

Did I miss something or is that feature not implemented?

Thanks in advance for helping me out!

UPDATE : I managed to get serialized objects directly out of the post method nativly, which I though was not possible. This doesn't solve the auto-doc problem but is still very valuable.

Answer 1

Restler 3 RC4 is released yesterday with the custom class parameters feature

Read http://restler3.luracast.com/param.html#type for an example and testing code

Answer 2

@igoru for your question in the comment use PHPDOC before function documentation

 * @param {type} $variable {comment} **{@from body}**

that's **{@from body}** would make the variable sent by request body .

if you wants to send it from php , use the following :

<?php
$data = array("name" => "Another", "email" => "another@email.com");
$data_string = json_encode($data);

$ch = curl_init("http://restler3.luracast.com/examples/_007_crud/index.php/authors");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
        'Content-Type: application/json',
        'Content-Length: ' . strlen($data_string))
);

$result = curl_exec($ch);
echo($result);