5

我正在使用 Symfony 框架，并打算将自动文档引擎添加到我项目的 RESTful api 中。

经过一番搜索，我找到了 apidoc 引擎（http://apidocjs.com/）。它的工作原理非常简单：您必须为 RESTful api 的每个控制器添加一些注释，然后生成文档。

注解的例子是：

/**
 * @Route("/api/dictionary_list/{userId}/{sessionKey}", name="api/dictionary_list")
 * @api {get} /api/dictionary_list/{userId}/{sessionKey} 01. Values list (ids) for all system dictionaries
 * @apiName Dictionary list
 * @apiGroup Dictionary
 *
 * @apiParam {Integer} userId  User's ID received in authorization request
 * @apiParam {String} sessionKey  Session key received in authorization request
 *
 * @apiSuccess {Integer} parcelStatuses  The name of current dictionary
 * @apiSuccess {String} itemId  Item id which used in requests
 * @apiSuccess {String} itemName  Item name
 */

public function dictionaryListAction($userId=null, $sessionKey=null)
{
 ...
}

可以看到，apidoc 的注解和 Symfony 中路由的注解是一样的。

顺便说一句，在生产环境中它工作正常，但在开发环境中我得到异常

[Semantical Error] The annotation "@apiName" in method AppBundle\Controller\Api\apiDictionaryController::dictionaryListAction() was never imported.

有什么办法可以解决这个问题并向 Symfony 说必须忽略 apidoc 的注释？

4

4 回答 4

2

您可以使用IgnoreAnnotation注释告诉 Docrine 注释阅读器在您的控制器中跳过此注释。为此，只需将注释添加@IgnoreAnnotation("Annotation")到类的类文档注释中。

在你的情况下：

/**
 * @IgnoreAnnotation("apiName")
 * @IgnoreAnnotation("apiGroup")
 * @IgnoreAnnotation("apiParam")
 * @IgnoreAnnotation("apiSuccess")
 */
class ActionController extends Controller


/**
 * @Route("/api/dictionary_list/{userId}/{sessionKey}", name="api/dictionary_list")
 * @api {get} /api/dictionary_list/{userId}/{sessionKey} 01. Values list (ids) for all system dictionaries
 * @apiName Dictionary list
 * @apiGroup Dictionary
 *
 * @apiParam {Integer} userId  User's ID received in authorization request
 * @apiParam {String} sessionKey  Session key received in authorization request
 *
 * @apiSuccess {Integer} parcelStatuses  The name of current dictionary
 * @apiSuccess {String} itemId  Item id which used in requests
 * @apiSuccess {String} itemName  Item name
 */

public function dictionaryListAction($userId=null, $sessionKey=null)
{
 ...
}

您还可以考虑为学说/注释项目打开一个 PR，以将此注释作为默认跳过作为this one包含在内。

希望这有帮助。

于 2016-07-01T20:05:08.740 回答
1

在 DI 容器编译期间读取注释，因此在编译器传递期间忽略 apidocs 注释可能是一个更好的主意。

例子：

<?php
namespace YourBundle\DependencyInjection;

use Doctrine\Common\Annotations\AnnotationReader;
use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
use Symfony\Component\DependencyInjection\ContainerBuilder;

class IgnoreApiDocsAnnotationsPass implements CompilerPassInterface {
    public function process(ContainerBuilder $container) {
        AnnotationReader::addGlobalIgnoredName('api');
        AnnotationReader::addGlobalIgnoredName('apiDefine');
        AnnotationReader::addGlobalIgnoredName('apiDeprecated');
        AnnotationReader::addGlobalIgnoredName('apiDescription');
        AnnotationReader::addGlobalIgnoredName('apiError');
        AnnotationReader::addGlobalIgnoredName('apiErrorExample');
        AnnotationReader::addGlobalIgnoredName('apiExample');
        AnnotationReader::addGlobalIgnoredName('apiGroup');
        AnnotationReader::addGlobalIgnoredName('apiHeader');
        AnnotationReader::addGlobalIgnoredName('apiHeaderExample');
        AnnotationReader::addGlobalIgnoredName('apiIgnore');
        AnnotationReader::addGlobalIgnoredName('apiName');
        AnnotationReader::addGlobalIgnoredName('apiParam');
        AnnotationReader::addGlobalIgnoredName('apiParamExample');
        AnnotationReader::addGlobalIgnoredName('apiPermission');
        AnnotationReader::addGlobalIgnoredName('apiPrivate');
        AnnotationReader::addGlobalIgnoredName('apiSampleRequest');
        AnnotationReader::addGlobalIgnoredName('apiSuccess');
        AnnotationReader::addGlobalIgnoredName('apiSuccessExample');
        AnnotationReader::addGlobalIgnoredName('apiUse');
        AnnotationReader::addGlobalIgnoredName('apiVersion');
    }
}

我从apidoc docs获得了完整的注释列表。您需要在您的捆绑包中注册编译器通行证

<?php
namespace YourBundle;

use YourBundle\DependencyInjection\IgnoreApiDocsAnnotationsPass;
use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\HttpKernel\Bundle\Bundle;

class YourBundle extends Bundle {
    public function build(ContainerBuilder $container) {
        parent::build($container);
        $container->addCompilerPass(new IgnoreApiDocsAnnotationsPass());
    }

}
于 2017-10-29T14:10:08.387 回答
1

Symfony 使用教义/注释包来解析注释。当它遇到尚未被列入黑名单的未知注释时，它会引发异常。

您可以将其他注释列入黑名单，请参阅Doctrine docs - Ignoring missing exceptions：

use Doctrine\Common\Annotations\AnnotationReader;

AnnotationReader::addGlobalIgnoredName('api');
AnnotationReader::addGlobalIgnoredName('apiParam');
AnnotationReader::addGlobalIgnoredName('apiGroup');
AnnotationReader::addGlobalIgnoredName('apiSuccess');

我会把它放在app/autoload.php中，因为它是一个全局设置。

于 2016-07-01T19:56:18.903 回答
-1

您必须导入 Route ：

使用 Sensio\Bundle\FrameworkExtraBundle\Configuration\Route；

于 2017-10-11T17:07:17.537 回答