Swagger-PHP和CakePHP

Question

我试图在我的CakePHP项目中使用Swagger-PHP，我遇到了一些问题。有人设置了吗？你有什么建议吗？我已经通过作曲家成功安装了swagger-php，并将其加载到我的控制器中（参见下文）。我试图通过网络视图呈现规范，我不太确定为什么注册表没有被填充或甚至需要。

以下是ApiController.php

结果

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' 
} 

所以

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' 
)); 
} 

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

Answer 1

我写的生成所有招摇文件（要求招摇的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

谢谢您的回答鲍勃，我意识到如何真正排除目录。无论如何，以下工作到目前为止。现在我只需要更好地处理实际的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="https://stackoverflow.com/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和团体定制的操作和参数，我已经增加。只要将这些添加到zircote/swagger-php/library/Swagger/Annotations /（Parameter and Operation）.php文件中即可。这些是3scale.net特定的项目。