Я использую инфраструктуру Symfony и имею намерение добавить механизм автоматической документации в RESTful api моего проекта.
После некоторых поисков я нашел apidoc engine ( 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 должна игнорироваться?
Вы можете использовать аннотацию 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 для проекта doctrine / annotations, чтобы включить эту аннотацию по умолчанию, пропущенную как эта .
Надеюсь, эта помощь.
Symfony использует пакет doctrine / annotations для анализа аннотаций. Когда он сталкивается с неизвестной аннотацией, которая не была включена в черный список, она выдает исключение.
Вы можете добавить в черный список дополнительные аннотации, см. Doctrine docs – Игнорирование отсутствующих исключений :
use Doctrine\Common\Annotations\AnnotationReader; AnnotationReader::addGlobalIgnoredName('api'); AnnotationReader::addGlobalIgnoredName('apiParam'); AnnotationReader::addGlobalIgnoredName('apiGroup'); AnnotationReader::addGlobalIgnoredName('apiSuccess');
Я бы поставил это в app / autoload.php, поскольку это глобальная настройка.
Аннотации читаются во время компиляции DI Container, поэтому может быть лучше проигнорировать аннотации 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 . Вам необходимо зарегистрировать пропуск компилятора в своем комплекте
<?php namespace YourBundle; use SuplaWebApiBundle\DependencyInjection\IgnoreApiDocsAnnotationsPass; use Symfony\Component\DependencyInjection\ContainerBuilder; use Symfony\Component\HttpKernel\Bundle\Bundle; class SuplaWebApiBundle extends Bundle { public function build(ContainerBuilder $container) { parent::build($container); $container->addCompilerPass(new IgnoreApiDocsAnnotationsPass()); } }
Вам необходимо импортировать Route:
используйте Sensio \ Bundle \ FrameworkExtraBundle \ Configuration \ Route;