Describing response object in API-Explorer/Swagger

Question

I'm using Restler 3's API-Explorer which is a fork of Swagger-UI and am wondering if anyone has found an effective way of documenting/describing the response JSON object that the API returns. Obviously some of this -- in a "read between the lines" sort of way -- is available when you interactively try out the API but I'd like some way of indicating more verbosely the structure of the response. Has anyone come up with anything for this?

Answer 1

You do that with the @return PHPDoc comment.

For an example, take a look at the Rate Limiting Example in the explorer for

GET authors.json/{id}

you will find Response Information listing

Author ( name: string, email: string )

It is coming from the following class set as the return type

<?php
/**
 * Dummy class, used only for creating swagger spec model (json schema)
 * look at the generated resources json to understand
 */
class Author
{
    public $name='Name';
    public $email='name@domain.com';
}