Swagger-PHP and CakePHP

我写了一个Controller来生成所有的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);
    }
}

谢谢你的回答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 and Operation).php文件中。这些都是3scale.net特有的项目