I am not familiar with cake; however based on the example I was given this should produce the desired result.

cake-example.php

<?php
use Swagger\Annotations as SWG;
App::uses('AppController', 'Controller');
/**
 * Users Controller
 * @SWG\Resource(
 *      apiVersion="0.2",
 *      swaggerVersion="1.1",
 *      basePath="http://api.myhost.local/api",
 *      resourcePath="/users"
 * )
 */
class UsersController extends AppController {

/**
 * view method
 * @SWG\Api(
 *   path="/user.{format}/{id}", description="Operations for users",
 *   @SWG\operations(
 *     @SWG\operation(
 *       httpMethod="GET", summary="Find user by ID",
 *       responseClass="User", nickname="getUserById", notes="Returns a user based on ID",
 *       @SWG\parameters(
 *         @SWG\parameter(name="id",
 *           description="The id that needs to be fetched. ",
 *           paramType="path", required="true", allowMultiple=false, dataType="string"
 *         )
 *       ),
 *       @SWG\errorResponses(
 *          @SWG\errorResponse(code="400", reason="Invalid id supplied"),
 *          @SWG\errorResponse(code="404", reason="User not found")
 *       )
 *     )
 *   )
 * )
 *
 * @throws NotFoundException
 * @throws ValidationException
 * @param string $id
 * @return void
 */
    public function view($id = null) {
        // actual code redacted
    }
}


/**
 * @package
 * @category
 * @subpackage
 *
 * @SWG\Model(id="User")
 */
class User
{
    /**
     * @var string
     * @SWG\Property(name="id",type="string")
     */
    protected $id;
}

A good resource for working examples would be the test fixtures in the project also.

I found I had to modify this code slightly:

<?php
use Swagger\Annotations;
use Swagger\Annotations\Api;
use Swagger\Annotations\ErrorResponses;
use Swagger\Annotations\ErrorResponse;
use Swagger\Annotations\Operation;
use Swagger\Annotations\Operations;
use Swagger\Annotations\Parameters;
use Swagger\Annotations\Parameter;
use Swagger\Annotations\Resource;
App::uses('AppController', 'Controller');

and change any reference to @SWG\Api etc to @Api - this applies to all @swg references e.g. @swg\Resources, @swg\Parameters, @swg\Parameter

I found running the .phar file to be the most successful:

php /var/www/cakesite/app/Vendor/zircote/swagger-php/swagger.phar -p ./Controller -o /var/www/cakesite/app/webroot/api-docs/generated -f -i /var/www/engage/app/webroot/index.php &> ~/Documents/tmp.html

The &> is used to send all output from the terminal to a tmp.html in ~/Documents, so I can load it up in my browser to check for any feedback. This is useful as it shows CakePHP errors, if Debug > 0 in app/Config/core.php