README

用法

将 vegas-cmf/apidoc 添加到 composer.json 依赖项中

"vegas-cmf/apidoc" : "1.0.*"

并运行 composer update

php composer.phar update

创建一个扩展 \Vegas\ApiDoc\Task\GeneratorTaskAbstract.php 的 CLI 任务

mkdir app/tasks

touch app/tasks/ApidocTask.php

//app/tasks/ApidocTask.php
use Vegas\Cli\Task\Option;
use Vegas\Mvc\View;

class ApidocTask extends \Vegas\ApiDoc\Task\GeneratorTaskAbstract
{
    protected function getView()
    {
        $view = new View($this->di->get('config')->application->view->toArray());
        $view->setDI($this->di);

        return $view;
    }

    protected function getOutputPath()
    {
        return APP_ROOT . '/public/apiDoc/';
    }

    protected function getLayoutFilePath()
    {
        return APP_ROOT . '/app/layouts/partials/apiDoc/layout';
    }

    protected function getInputPath()
    {
        return APP_ROOT . '/app/modules';
    }
}

向控制器类添加注释

<?php
namespace ApiTest\Controllers;

use ApiTest\Services\Exception\ApiException;
use Vegas\Mvc\Controller\ControllerAbstract;
use Phalcon\Mvc\Dispatcher;

/**
 * @api(
 *  name='Test',
 *  description='Test API',
 *  version='1.0.0'
 * )
 */
class TestController extends ControllerAbstract
{
    /**
     * @api(
     *  method='GET',
     *  description='Returns Test object',
     *  name='Get test',
     *  url='/api/test/{id}',
     *  params=[
     *      {name: 'id', type: 'string', description: 'Test ID'}
     *  ],
     *  headers=[
     *      {name: 'HTTP_X_AUTH', description: 'Authentication token'}
     *  ],
     *  requestFormat='JSON',
     *  requestContentType='application/json',
     *  request={
     *      {name: 'id', type: 'MongoId', description: 'ID of something'}
     *  },
     *  requestExample='{
     *      "id": "123"
     *  }',
     *  responseFormat='JSON',
     *  responseContentType='application/json',
     *  response=[
     *      {name: 'id', type: 'MongoId', description: 'Test ID'},
     *      {name: 'name', type: 'string', description: 'Foo name'}
     *  ],
     *  responseCodes=[
     *      {code: 111, description: 'Connection refused'},
     *      {code: 200, description: 'OK'},
     *      {code: 300, description: 'Found'},
     *      {code: 404, description: 'Record not found'},
     *      {code: 500, description: 'Application error'}
     *  ],
     *  responseExample='{
     *      "id": "123",
     *      "name": "Test"
     *  }'
     * )
     */
    public function getAction()
    {
        try {
            if (!$this->request->get('id')) {
                throw new ApiException();
            }
            return $this->jsonResponse(
                [
                    'id' => '123',
                    'name' => 'Test 1'
                ]
            );
        } catch (ApiException $e) {
            $response = $this->jsonResponse('');
            $response->setStatusCode(404, 'Record not found');
            return $response;
        } catch (\Exception $e) {
            $response = $this->jsonResponse('');
            $response->setStatusCode(500, 'Application error');
            return $response;
        }
    }

    /**
     * @api(
     *  method='GET',
     *  description='Returns list of tests objects',
     *  name='Get tests',
     *  url='/api/test',
     *  headers=[
     *      {name: 'HTTP_X_AUTH', description: 'Authentication token'}
     *  ],
     *  responseCodes=[
     *      {code: 500, description: 'Unknown error'}
     *      {code: 200, description: 'Ok'}
     *  ],
     *  requestFormat='JSON',
     *  requestContentType='application/json',
     *  request=''
     *  requestExample='',
     *  responseFormat='JSON',
     *  responseContentType='application/json',
     *  response=[
     *      {
     *          {name: 'id', type: 'MongoId', description: 'Test ID'},
     *          {name: 'name', type: 'string', description: 'Test name'}
     *      },
     *      {
     *          {name: 'id', type: 'MongoId', description: 'Test ID'},
     *          {name: 'name', type: 'string', description: 'Test name'}
     *      }
     *  ],
     *  responseExample='[
     *      {
     *          "id": "123",
     *          "name": "Test 1"
     *      },
     *      {
     *          "id": "124",
     *          "name": "Test 2"
     *      }
     *  ]'
     * )
     * @return null|\Phalcon\Http\ResponseInterface
     */
    public function listAction()
    {
        try {
            return $this->jsonResponse(
                [
                    'id' => '123',
                    'name' => 'Test 1'
                ],
                [
                    'id' => '124',
                    'name' => 'Test 2'
                ]
            );
        } catch (\Exception $e) {
            $response = $this->jsonResponse('');
            $response->setStatusCode(500, 'Application  error');
            return $response;
        }
    }
}

可用参数

类

name 端点名称

description API 端点的详细描述

version API 版本

方法

name API 方法的名称

description API 方法的详细描述

method 确定HTTP方法（POST，GET等）

url 请求路径

params 描述传递给API方法的参数

headers 描述请求中的头部，例如授权

request 描述请求

requestContentType 确定请求 Content-Type

requestFormat 确定请求格式

requestExample 请求体的示例

response 描述响应

responseContentType 确定响应 Content-Type

responseFormat 确定响应格式

responseExample 响应体的示例

responseCodes 描述响应状态码

创建文档布局（您可以使用 tests/fixtures/app/layouts/partials/apiDoc 目录中的示例布局）并准备输出目录

mkdir app/layouts/partials -p

touch cp -R vendor/vegas-cmf/apidoc/tests/fixtures/app/layouts/partials/apiDoc app/layouts/partials/.

mkdir public/apiDoc

运行 CLI 任务以生成文档

php cli/cli.php app:apidoc generate

请参阅示例 http://jsbin.com/xeyetevuro/1