Symfony - 註釋從未導入

Question

我正在使用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已被忽略？

Answer 1

您可以使用IgnoreAnnotation註釋來告訴Docrine註釋閱讀器在您的控制器中跳過此註釋。爲此，只需將註釋add @IgnoreAnnotation("Annotation")添加到類的class doc註釋中即可。

在你的情況：

/** 
* @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) 
{ 
... 
} 

你也可以考慮開個公關的doctrine/annotations項目，包括這個註解爲默認跳過作爲this one。

希望得到這個幫助。

Answer 2

Symfony使用doctrine/annotations包來解析註釋。當遇到尚未列入黑名單的未知註解時，會引發異常。

你可以黑名單附加註釋，請參閱Doctrine docs - Ignoring missing exceptions：

use Doctrine\Common\Annotations\AnnotationReader; 

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

我把這個在應用程序/ autoload.php，因爲它是一個全球性的設置。

Answer 3

您必須導入路線：

使用Sensio公司\包\ FrameworkExtraBundle \配置\路徑;

Answer 4

在DI容器編譯過程中讀取註解，因此在compiler pass期間忽略apidoc註釋可能是一個更好的主意。

例子：

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

我obtainted從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()); 
    } 

}