Swagger-PHP和CakePHP

Question

我正尝试在我的CakePHP项目中使用Swagger-PHP，但我遇到了一些问题。有人设置好了吗？你有什么建议吗？我已经通过composer成功地安装了swagger-php，并将其加载到我的控制器中(如下所示)。我试图通过web视图呈现一个规范，但我不太确定为什么注册表没有被填充，或者是否需要填充注册表。

下面是ApiController.php内部的代码

use Swagger\Annotations as SWG; 
use Swagger\Swagger;

public function swagger(){
    $path = APP . 'Model'; //Path to the app directory
$swagger = Swagger::discover($path,APP . 'Model/Behavior');
debug($swagger);
 //$swagger->jsonEncode($swagger->registry['/api']);
$swagResults = $swagger->registry;
debug($swagResults);
$this->set(array(
    'results' => $swagResults,
    '_serialize' => 'results'
));
}

结果

object(Swagger\Swagger) {
    resourceList => array()
    registry => array()
    models => array()
    [protected] fileList => array(
        (int) 0 => '~/Sites/com/sitename-api/app/Model/[ModelName].php',
        ... All of my models
    )
    [protected] path => '~/Sites/com/sitename-api/app/Model'
    [protected] excludePath => '~/Sites/com/sitename-api/app/Model/Behavior'
    [protected] cache => object(Doctrine\Common\Cache\ArrayCache) {
        [private] data => array(
            'DoctrineNamespaceCacheKey[]' => (int) 1,
            '[][1]' => 'a:4:{s:8:"registry";a:0:{}s:6:"models";a:0:{}s:4:"path";N;s:11:"excludePath";N;}',
            '[cd9db43f54f6017ba1a20037c1577eb4d2017868][1]' => 'a:4:{s:8:"registry";a:0:{}s:6:"models";a:0:{}s:4:"path";s:56:"~/Sites/com/sitename-api/app/Model";s:11:"excludePath";s:65:"~/Sites/com/sitename-api/app/Model/Behavior";}'
        )
    }
    [protected] cacheKey => 'cd9db43f54f6017ba1a20037c1577eb4d2017868'
}

所以，基本上$swagResults是空的，我猜这不应该是空的，对吧？

Answer 1

我编写了一个控制器来生成所有swagger文档(需要swagger-php 0.6或更高版本)：

<?php
use Swagger\Swagger;
class SwaggerController extends AppController {

    function index() {
        $swagger = Swagger::discover(APP, TMP.':'.APP.'Vendor');

        $this->autoRender = false;
        if (isset($this->request->query['resource'])) {
            return $swagger->getResource($this->request->query['resource']);
        }
        $list = array(
            "apiVersion" => "1.0",
            "swaggerVersion" => "1.1",
            "basePath" => Router::url(array('?' => array('resource' =>'')), true),
            "apis" => array()
        );
        foreach ($swagger->registry as $name => $resource) {
            $item = array("path" => $name);
            foreach ($resource->apis as $api) {
                if ($api->description !== null) {
                    $item['description'] = $api->description;
                    break;
                }
            }
            $list['apis'][] = $item;
        }
        return json_encode($list);
    }
}

Answer 2

谢谢你的回答，Bob，我意识到了如何实际排除目录。不管怎样，到目前为止，下面的方法是可行的。现在我只需要更好地掌握实际的Swagger规范。

在您的模型中，添加以下内容：

use Swagger\Annotations as SWG;

/**
 * User Model
 * @SWG\Model(
 *      id="User",
 *      description="Defines a user."
 * )
 */

在控制器中，添加以下内容。注意: controller_name是将被传递给swagger方法的对象。

use Swagger\Annotations as SWG;

/**
 * @SWG\Resource(
 *      resourcePath="/users"
 * )
 */

在API控制器中构建如下所示的方法。

/**
 * swagger method
 * This method renders the Swagger spec
 * @param string $controller The controller a.k.a resource to pull Swagger docs for
 * @return array
 */
public function swagger($controller = ''){
    if(!empty($resource)) {
        $this->request->query['resource'] = '/'.$controller;
    }
    $path = APP; //Path to the app directory
    $path = substr($path, 0, -1);
    $swagger = Swagger::discover(
            $path, 
            APP . 'Plugin:' . 
            APP . 'Vendor:' . 
            APP . 'Config:' . 
            APP . 'Test:' .
            APP . 'Console:' .
            //APP . 'Model:' .
            APP . 'View/Helper:' .
            APP . 'Controller/Component:' .
            APP . 'webroot:' .
            APP . 'tmp:' .
            APP . 'index.php:' .
            'libs:' .
            'plugins:' .
            'vendors' 
        );
    $swagger->setDefaultApiVersion(Configure::read('CC.version'));
    $swagger->setDefaultBasePath(Configure::read('CC.site_url') . DS . Configure::read('CC.version'));
    $swagger->setDefaultSwaggerVersion(SWAGGER_VERSION);
    $this->autoRender = false;
    if (isset($this->request->query['resource'])) {
        return $swagger->getResource($this->request->query['resource']);
    }
    $list = array(
        "apiVersion" => API_VERSION,
        "swaggerVersion" => "1.1",
        "basePath" => Router::url(array('?' => array('resource' =>'')), true),
        "apis" => array()
    );
    if (isset($this->request->query['resource'])) {
        return $swagger->getResource($this->request->query['resource']);
    }
    $list['apis'][] = $swagger->registry;
    $this->set(array(
        'results' => $list,
        '_serialize' => 'results'
    ));
}

方法注释可能如下所示：

/**
 * info method
 * This provides an app with basic user information. 
 * @param int id The user id
 * @return array 
 * @SWG\Api(
 *      path="/users/info/{user_id}.{format}",
 *      description="This provides an app with basic user information.",
 *      @SWG\Operations(
 *          @SWG\Operation(
 *              httpMethod="GET",
 *              summary="User Basic Info",
 *              notes="",
 *              responseClass="List[User]",
 *              nickname="getUserInfo",
 *              group="users",
 *              @SWG\Parameters(
 *                  @SWG\Parameter(
 *                      name="format",
 *                      description="The format that the data will be returned in.",
 *                      paramType="path",
 *                      required="true",
 *                      allowMultiple="false",
 *                      dataType="Array",
 *                      @SWG\AllowableValues(
 *                          valueType="LIST",
 *                          values="['json', 'xml']"
 *                      )
 *                  ),
 *                  @SWG\Parameter(
 *                      name="user_id",
 *                      description="The user id",
 *                      paramType="path",
 *                      required="true",
 *                      allowMultiple="false",
 *                      dataType="int"
 *                  ),
 *                  @SWG\Parameter(
 *                      name="client_id",
 *                      description="Your client id",
 *                      paramType="query",
 *                      required="true",
 *                      allowMultiple="false",
 *                      dataType="string",
 *                      threescale_name="client_ids"
 *                  )
 *              ),
 *              @SWG\ErrorResponses(
 *                  @SWG\ErrorResponse(
 *                      code="404",
 *                      reason="User not found"
 *                  )
 *              )
 *          )
 *      )
 *  )
 */

注意: threescale_name和groups是我添加的自定义操作和参数。如果您想使用它们，只需将它们添加到zircote/swagger-php/library/Swagger/Annotations/(Parameter和.php文件中即可。这些是特定于3scale.net的项目。