From 63b0f8e4da36bfba843f57bdd7acdcf980c8a744 Mon Sep 17 00:00:00 2001 From: fvilpoix Date: Fri, 12 Apr 2013 17:05:13 +0200 Subject: [PATCH 1/4] Moving annotation extraction into tagged Handlers --- DependencyInjection/NelmioApiDocExtension.php | 14 ++++++ Extractor/ApiDocExtractor.php | 46 +++++-------------- Extractor/Handler/EmptyHandler.php | 22 +++++++++ .../Handler/FosRestQueryParamHandler.php | 40 ++++++++++++++++ .../Handler/FosRestRequestParamHandler.php | 34 ++++++++++++++ .../Handler/JmsSecurityExtraSecureHandler.php | 29 ++++++++++++ .../SensioFrameworkExtraCacheHandler.php | 29 ++++++++++++ Extractor/HandlerInterface.php | 19 ++++++++ README.md | 14 ++++++ Resources/config/services.xml | 25 ++++++++++ 10 files changed, 237 insertions(+), 35 deletions(-) create mode 100644 Extractor/Handler/EmptyHandler.php create mode 100644 Extractor/Handler/FosRestQueryParamHandler.php create mode 100644 Extractor/Handler/FosRestRequestParamHandler.php create mode 100644 Extractor/Handler/JmsSecurityExtraSecureHandler.php create mode 100644 Extractor/Handler/SensioFrameworkExtraCacheHandler.php create mode 100644 Extractor/HandlerInterface.php diff --git a/DependencyInjection/NelmioApiDocExtension.php b/DependencyInjection/NelmioApiDocExtension.php index ce10263..9c04b28 100644 --- a/DependencyInjection/NelmioApiDocExtension.php +++ b/DependencyInjection/NelmioApiDocExtension.php @@ -16,6 +16,7 @@ use Symfony\Component\DependencyInjection\Loader\XmlFileLoader; use Symfony\Component\DependencyInjection\ContainerBuilder; use Symfony\Component\Config\Definition\Processor; use Symfony\Component\Config\FileLocator; +use Symfony\Component\DependencyInjection\Reference; class NelmioApiDocExtension extends Extension { @@ -48,5 +49,18 @@ class NelmioApiDocExtension extends Extension if (isset($config['sandbox']['authentication'])) { $container->setParameter('nelmio_api_doc.sandbox.authentication', $config['sandbox']['authentication']); } + + // Adding handlers from tagged services + $definition = $container->getDefinition( + 'nelmio_api_doc.extractor.api_doc_extractor' + ); + $taggedServices = $container->findTaggedServiceIds( + 'nelmio_api_doc.extractor.handler' + ); + $handlers = array(); + foreach ($taggedServices as $id => $attributes) { + $handlers[] = new Reference($id); + } + $definition->replaceArgument(4, $handlers); } } diff --git a/Extractor/ApiDocExtractor.php b/Extractor/ApiDocExtractor.php index e338fe9..6682e39 100644 --- a/Extractor/ApiDocExtractor.php +++ b/Extractor/ApiDocExtractor.php @@ -19,19 +19,12 @@ use Symfony\Component\Routing\RouterInterface; use Symfony\Component\DependencyInjection\ContainerInterface; use Symfony\Component\HttpFoundation\Request; use Nelmio\ApiDocBundle\Util\DocCommentExtractor; +use Nelmio\ApiDocBundle\Extractor\Handler\HandlerInterface; class ApiDocExtractor { const ANNOTATION_CLASS = 'Nelmio\\ApiDocBundle\\Annotation\\ApiDoc'; - const FOS_REST_QUERY_PARAM_CLASS = 'FOS\\RestBundle\\Controller\\Annotations\\QueryParam'; - - const FOS_REST_REQUEST_PARAM_CLASS = 'FOS\\RestBundle\\Controller\\Annotations\\RequestParam'; - - const JMS_SECURITY_EXTRA_SECURE_CLASS = 'JMS\\SecurityExtraBundle\\Annotation\\Secure'; - - const CACHE_ANNOTATION_CLASS = 'Sensio\\Bundle\\FrameworkExtraBundle\\Configuration\\Cache'; - /** * @var ContainerInterface */ @@ -57,12 +50,18 @@ class ApiDocExtractor */ protected $parsers = array(); - public function __construct(ContainerInterface $container, RouterInterface $router, Reader $reader, DocCommentExtractor $commentExtractor) + /** + * @var array HandlerInterface + */ + protected $handlers; + + public function __construct(ContainerInterface $container, RouterInterface $router, Reader $reader, DocCommentExtractor $commentExtractor, $handlers) { $this->container = $container; $this->router = $router; $this->reader = $reader; $this->commentExtractor = $commentExtractor; + $this->handlers = $handlers; } /** @@ -359,32 +358,9 @@ class ApiDocExtractor */ protected function parseAnnotations(ApiDoc $annotation, Route $route, \ReflectionMethod $method) { - foreach ($this->reader->getMethodAnnotations($method) as $annot) { - if (is_a($annot, self::FOS_REST_QUERY_PARAM_CLASS)) { - if ($annot->strict && $annot->default === null) { - $annotation->addRequirement($annot->name, array( - 'requirement' => $annot->requirements, - 'dataType' => '', - 'description' => $annot->description, - )); - } else { - $annotation->addFilter($annot->name, array( - 'requirement' => $annot->requirements, - 'description' => $annot->description, - )); - } - } elseif (is_a($annot, self::FOS_REST_REQUEST_PARAM_CLASS)) { - $annotation->addParameter($annot->name, array( - 'required' => $annot->strict && $annot->default === null, - 'dataType' => $annot->requirements, - 'description' => $annot->description, - 'readonly' => false - )); - } elseif (is_a($annot, self::JMS_SECURITY_EXTRA_SECURE_CLASS)) { - $annotation->setAuthentication(true); - } elseif (is_a($annot, self::CACHE_ANNOTATION_CLASS)) { - $annotation->setCache($annot->getMaxAge()); - } + $annots = $this->reader->getMethodAnnotations($method); + foreach ($this->handlers as $handler) { + $handler->handle($annotation, $annots); } } } diff --git a/Extractor/Handler/EmptyHandler.php b/Extractor/Handler/EmptyHandler.php new file mode 100644 index 0000000..1b1f958 --- /dev/null +++ b/Extractor/Handler/EmptyHandler.php @@ -0,0 +1,22 @@ + + * + * For the full copyright and license information, please view the LICENSE + * file that was distributed with this source code. + */ + +namespace Nelmio\ApiDocBundle\Extractor\Handler; + +use Nelmio\ApiDocBundle\Extractor\HandlerInterface; +use \Nelmio\ApiDocBundle\Annotation\ApiDoc; + +class EmptyHandler implements HandlerInterface +{ + public function handle(ApiDoc $annotation, $annotations) + { + } +} diff --git a/Extractor/Handler/FosRestQueryParamHandler.php b/Extractor/Handler/FosRestQueryParamHandler.php new file mode 100644 index 0000000..bcbf9db --- /dev/null +++ b/Extractor/Handler/FosRestQueryParamHandler.php @@ -0,0 +1,40 @@ + + * + * For the full copyright and license information, please view the LICENSE + * file that was distributed with this source code. + */ + +namespace Nelmio\ApiDocBundle\Extractor\Handler; + +use Nelmio\ApiDocBundle\Extractor\HandlerInterface; +use \Nelmio\ApiDocBundle\Annotation\ApiDoc; + +class FosRestQueryParamHandler implements HandlerInterface +{ + const FOS_REST_QUERY_PARAM_CLASS = 'FOS\\RestBundle\\Controller\\Annotations\\QueryParam'; + + public function handle(ApiDoc $annotation, $annotations) + { + foreach ($annotations as $annot) { + if (is_a($annot, self::FOS_REST_QUERY_PARAM_CLASS)) { + if ($annot->strict && $annot->default === null) { + $annotation->addRequirement($annot->name, array( + 'requirement' => $annot->requirements, + 'dataType' => '', + 'description' => $annot->description, + )); + } else { + $annotation->addFilter($annot->name, array( + 'requirement' => $annot->requirements, + 'description' => $annot->description, + )); + } + } + } + } +} diff --git a/Extractor/Handler/FosRestRequestParamHandler.php b/Extractor/Handler/FosRestRequestParamHandler.php new file mode 100644 index 0000000..1260bd4 --- /dev/null +++ b/Extractor/Handler/FosRestRequestParamHandler.php @@ -0,0 +1,34 @@ + + * + * For the full copyright and license information, please view the LICENSE + * file that was distributed with this source code. + */ + +namespace Nelmio\ApiDocBundle\Extractor\Handler; + +use Nelmio\ApiDocBundle\Extractor\HandlerInterface; +use \Nelmio\ApiDocBundle\Annotation\ApiDoc; + +class FosRestRequestParamHandler implements HandlerInterface +{ + const FOS_REST_REQUEST_PARAM_CLASS = 'FOS\\RestBundle\\Controller\\Annotations\\RequestParam'; + + public function handle(ApiDoc $annotation, $annotations) + { + foreach ($annotations as $annot) { + if (is_a($annot, self::FOS_REST_REQUEST_PARAM_CLASS)) { + $annotation->addParameter($annot->name, array( + 'required' => $annot->strict && $annot->default === null, + 'dataType' => $annot->requirements, + 'description' => $annot->description, + 'readonly' => false + )); + } + } + } +} diff --git a/Extractor/Handler/JmsSecurityExtraSecureHandler.php b/Extractor/Handler/JmsSecurityExtraSecureHandler.php new file mode 100644 index 0000000..1110ee1 --- /dev/null +++ b/Extractor/Handler/JmsSecurityExtraSecureHandler.php @@ -0,0 +1,29 @@ + + * + * For the full copyright and license information, please view the LICENSE + * file that was distributed with this source code. + */ + +namespace Nelmio\ApiDocBundle\Extractor\Handler; + +use Nelmio\ApiDocBundle\Extractor\HandlerInterface; +use \Nelmio\ApiDocBundle\Annotation\ApiDoc; + +class JmsSecurityExtraSecureHandler implements HandlerInterface +{ + const JMS_SECURITY_EXTRA_SECURE_CLASS = 'JMS\\SecurityExtraBundle\\Annotation\\Secure'; + + public function handle(ApiDoc $annotation, $annotations) + { + foreach ($annotations as $annot) { + if (is_a($annot, self::JMS_SECURITY_EXTRA_SECURE_CLASS)) { + $annotation->setAuthentication(true); + } + } + } +} diff --git a/Extractor/Handler/SensioFrameworkExtraCacheHandler.php b/Extractor/Handler/SensioFrameworkExtraCacheHandler.php new file mode 100644 index 0000000..1b22d86 --- /dev/null +++ b/Extractor/Handler/SensioFrameworkExtraCacheHandler.php @@ -0,0 +1,29 @@ + + * + * For the full copyright and license information, please view the LICENSE + * file that was distributed with this source code. + */ + +namespace Nelmio\ApiDocBundle\Extractor\Handler; + +use Nelmio\ApiDocBundle\Extractor\HandlerInterface; +use \Nelmio\ApiDocBundle\Annotation\ApiDoc; + +class SensioFrameworkExtraCacheHandler implements HandlerInterface +{ + const CACHE_ANNOTATION_CLASS = 'Sensio\\Bundle\\FrameworkExtraBundle\\Configuration\\Cache'; + + public function handle(ApiDoc $annotation, $annotations) + { + foreach ($annotations as $annot) { + if (is_a($annot, self::CACHE_ANNOTATION_CLASS)) { + $annotation->setCache($annot->getMaxAge()); + } + } + } +} diff --git a/Extractor/HandlerInterface.php b/Extractor/HandlerInterface.php new file mode 100644 index 0000000..bedf2ff --- /dev/null +++ b/Extractor/HandlerInterface.php @@ -0,0 +1,19 @@ + + * + * For the full copyright and license information, please view the LICENSE + * file that was distributed with this source code. + */ + +namespace Nelmio\ApiDocBundle\Extractor; + +use Nelmio\ApiDocBundle\Annotation\ApiDoc; + +interface HandlerInterface +{ + public function handle(ApiDoc $annotation, $annotations); +} diff --git a/README.md b/README.md index 0668cbb..a146aa2 100644 --- a/README.md +++ b/README.md @@ -236,6 +236,20 @@ You can also define your own motd content (above methods list). All you have to motd: template: AcmeApiBundle::Components/motd.html.twig +## Using your own annotations ## + +If you have developped your own project-related annotations, and you want to parse them to populate the ApiDoc, you can provide custom handlers as services. You juste have to implements the `Nelmio\ApiDocBundle\Extractor\HandlerInterface` and tag it as `nelmio_api_doc.extractor.handler`. + + #app/config/config.yml + services: + mybundle.api_doc.extractor.my_annotation_handler: + class: MyBundle\AnnotationHandler\MyAnnotationHandler; + tags: + - {name: nelmio_api_doc.extractor.handler} + +Look at examples in [Handlers](https://github.com/nelmio/NelmioApiDocBundle/tree/annotation_handlers/Extractor/Handler) + + ## Credits ## The design is heavily inspired by the [swagger-ui](https://github.com/wordnik/swagger-ui) project. diff --git a/Resources/config/services.xml b/Resources/config/services.xml index c1f9f7e..c53998c 100644 --- a/Resources/config/services.xml +++ b/Resources/config/services.xml @@ -8,6 +8,11 @@ Nelmio\ApiDocBundle\Form\Extension\DescriptionFormTypeExtension Nelmio\ApiDocBundle\Twig\Extension\MarkdownExtension Nelmio\ApiDocBundle\Util\DocCommentExtractor + + Nelmio\ApiDocBundle\Extractor\Handler\FosRestQueryParamHandler + Nelmio\ApiDocBundle\Extractor\Handler\FosRestRequestParamHandler + Nelmio\ApiDocBundle\Extractor\Handler\JmsSecurityExtraSecureHandler + Nelmio\ApiDocBundle\Extractor\Handler\SensioFrameworkExtraCacheHandler @@ -18,6 +23,7 @@ + @@ -27,6 +33,25 @@ + + + + + + + + + + + + + + + + + + + From 76b85938c6c8683e1ab28265e1f23aea2b4c190c Mon Sep 17 00:00:00 2001 From: fvilpoix Date: Tue, 16 Apr 2013 13:46:15 +0200 Subject: [PATCH 2/4] implementing all stof comments :) --- .../ExtractorHandlerCompilerPass.php | 37 +++++++++++++++++++ DependencyInjection/NelmioApiDocExtension.php | 13 ------- Extractor/ApiDocExtractor.php | 5 +-- Extractor/Handler/EmptyHandler.php | 22 ----------- ...eryParamHandler.php => FosRestHandler.php} | 17 +++++++-- .../Handler/FosRestRequestParamHandler.php | 34 ----------------- ...andler.php => JmsSecurityExtraHandler.php} | 7 ++-- ...er.php => SensioFrameworkExtraHandler.php} | 7 ++-- Extractor/HandlerInterface.php | 4 +- NelmioApiDocBundle.php | 2 + Resources/config/services.xml | 17 +++------ 11 files changed, 71 insertions(+), 94 deletions(-) create mode 100644 DependencyInjection/ExtractorHandlerCompilerPass.php delete mode 100644 Extractor/Handler/EmptyHandler.php rename Extractor/Handler/{FosRestQueryParamHandler.php => FosRestHandler.php} (58%) delete mode 100644 Extractor/Handler/FosRestRequestParamHandler.php rename Extractor/Handler/{JmsSecurityExtraSecureHandler.php => JmsSecurityExtraHandler.php} (72%) rename Extractor/Handler/{SensioFrameworkExtraCacheHandler.php => SensioFrameworkExtraHandler.php} (72%) diff --git a/DependencyInjection/ExtractorHandlerCompilerPass.php b/DependencyInjection/ExtractorHandlerCompilerPass.php new file mode 100644 index 0000000..6e7a697 --- /dev/null +++ b/DependencyInjection/ExtractorHandlerCompilerPass.php @@ -0,0 +1,37 @@ + + * + * For the full copyright and license information, please view the LICENSE + * file that was distributed with this source code. + */ + +namespace Nelmio\ApiDocBundle\DependencyInjection; + +use Symfony\Component\DependencyInjection\ContainerBuilder; +use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface; +use Symfony\Component\DependencyInjection\Reference; + + +class ExtractorHandlerCompilerPass implements CompilerPassInterface +{ + /** + * {@inheritDoc} + */ + public function process(ContainerBuilder $container) + { + $handlers = array(); + foreach ($container->findTaggedServiceIds('nelmio_api_doc.extractor.handler') as $id => $attributes) { + + // Adding handlers from tagged services + $handlers[] = new Reference($id); + } + $definition = $container->getDefinition( + 'nelmio_api_doc.extractor.api_doc_extractor' + ); + $definition->replaceArgument(4, $handlers); + } +} diff --git a/DependencyInjection/NelmioApiDocExtension.php b/DependencyInjection/NelmioApiDocExtension.php index 9c04b28..6298f78 100644 --- a/DependencyInjection/NelmioApiDocExtension.php +++ b/DependencyInjection/NelmioApiDocExtension.php @@ -49,18 +49,5 @@ class NelmioApiDocExtension extends Extension if (isset($config['sandbox']['authentication'])) { $container->setParameter('nelmio_api_doc.sandbox.authentication', $config['sandbox']['authentication']); } - - // Adding handlers from tagged services - $definition = $container->getDefinition( - 'nelmio_api_doc.extractor.api_doc_extractor' - ); - $taggedServices = $container->findTaggedServiceIds( - 'nelmio_api_doc.extractor.handler' - ); - $handlers = array(); - foreach ($taggedServices as $id => $attributes) { - $handlers[] = new Reference($id); - } - $definition->replaceArgument(4, $handlers); } } diff --git a/Extractor/ApiDocExtractor.php b/Extractor/ApiDocExtractor.php index 6682e39..91c41d8 100644 --- a/Extractor/ApiDocExtractor.php +++ b/Extractor/ApiDocExtractor.php @@ -19,7 +19,6 @@ use Symfony\Component\Routing\RouterInterface; use Symfony\Component\DependencyInjection\ContainerInterface; use Symfony\Component\HttpFoundation\Request; use Nelmio\ApiDocBundle\Util\DocCommentExtractor; -use Nelmio\ApiDocBundle\Extractor\Handler\HandlerInterface; class ApiDocExtractor { @@ -55,7 +54,7 @@ class ApiDocExtractor */ protected $handlers; - public function __construct(ContainerInterface $container, RouterInterface $router, Reader $reader, DocCommentExtractor $commentExtractor, $handlers) + public function __construct(ContainerInterface $container, RouterInterface $router, Reader $reader, DocCommentExtractor $commentExtractor, array $handlers) { $this->container = $container; $this->router = $router; @@ -360,7 +359,7 @@ class ApiDocExtractor { $annots = $this->reader->getMethodAnnotations($method); foreach ($this->handlers as $handler) { - $handler->handle($annotation, $annots); + $handler->handle($annotation, $annots, $route, $method); } } } diff --git a/Extractor/Handler/EmptyHandler.php b/Extractor/Handler/EmptyHandler.php deleted file mode 100644 index 1b1f958..0000000 --- a/Extractor/Handler/EmptyHandler.php +++ /dev/null @@ -1,22 +0,0 @@ - - * - * For the full copyright and license information, please view the LICENSE - * file that was distributed with this source code. - */ - -namespace Nelmio\ApiDocBundle\Extractor\Handler; - -use Nelmio\ApiDocBundle\Extractor\HandlerInterface; -use \Nelmio\ApiDocBundle\Annotation\ApiDoc; - -class EmptyHandler implements HandlerInterface -{ - public function handle(ApiDoc $annotation, $annotations) - { - } -} diff --git a/Extractor/Handler/FosRestQueryParamHandler.php b/Extractor/Handler/FosRestHandler.php similarity index 58% rename from Extractor/Handler/FosRestQueryParamHandler.php rename to Extractor/Handler/FosRestHandler.php index bcbf9db..8ad2602 100644 --- a/Extractor/Handler/FosRestQueryParamHandler.php +++ b/Extractor/Handler/FosRestHandler.php @@ -12,16 +12,25 @@ namespace Nelmio\ApiDocBundle\Extractor\Handler; use Nelmio\ApiDocBundle\Extractor\HandlerInterface; -use \Nelmio\ApiDocBundle\Annotation\ApiDoc; +use Nelmio\ApiDocBundle\Annotation\ApiDoc; +use Symfony\Component\Routing\Route; -class FosRestQueryParamHandler implements HandlerInterface +class FosRestHandler implements HandlerInterface { + const FOS_REST_REQUEST_PARAM_CLASS = 'FOS\\RestBundle\\Controller\\Annotations\\RequestParam'; const FOS_REST_QUERY_PARAM_CLASS = 'FOS\\RestBundle\\Controller\\Annotations\\QueryParam'; - public function handle(ApiDoc $annotation, $annotations) + public function handle(ApiDoc $annotation, $annotations, Route $route, \ReflectionMethod $method) { foreach ($annotations as $annot) { - if (is_a($annot, self::FOS_REST_QUERY_PARAM_CLASS)) { + if (is_a($annot, self::FOS_REST_REQUEST_PARAM_CLASS)) { + $annotation->addParameter($annot->name, array( + 'required' => $annot->strict && $annot->default === null, + 'dataType' => $annot->requirements, + 'description' => $annot->description, + 'readonly' => false + )); + } elseif (is_a($annot, self::FOS_REST_QUERY_PARAM_CLASS)) { if ($annot->strict && $annot->default === null) { $annotation->addRequirement($annot->name, array( 'requirement' => $annot->requirements, diff --git a/Extractor/Handler/FosRestRequestParamHandler.php b/Extractor/Handler/FosRestRequestParamHandler.php deleted file mode 100644 index 1260bd4..0000000 --- a/Extractor/Handler/FosRestRequestParamHandler.php +++ /dev/null @@ -1,34 +0,0 @@ - - * - * For the full copyright and license information, please view the LICENSE - * file that was distributed with this source code. - */ - -namespace Nelmio\ApiDocBundle\Extractor\Handler; - -use Nelmio\ApiDocBundle\Extractor\HandlerInterface; -use \Nelmio\ApiDocBundle\Annotation\ApiDoc; - -class FosRestRequestParamHandler implements HandlerInterface -{ - const FOS_REST_REQUEST_PARAM_CLASS = 'FOS\\RestBundle\\Controller\\Annotations\\RequestParam'; - - public function handle(ApiDoc $annotation, $annotations) - { - foreach ($annotations as $annot) { - if (is_a($annot, self::FOS_REST_REQUEST_PARAM_CLASS)) { - $annotation->addParameter($annot->name, array( - 'required' => $annot->strict && $annot->default === null, - 'dataType' => $annot->requirements, - 'description' => $annot->description, - 'readonly' => false - )); - } - } - } -} diff --git a/Extractor/Handler/JmsSecurityExtraSecureHandler.php b/Extractor/Handler/JmsSecurityExtraHandler.php similarity index 72% rename from Extractor/Handler/JmsSecurityExtraSecureHandler.php rename to Extractor/Handler/JmsSecurityExtraHandler.php index 1110ee1..6dfca7a 100644 --- a/Extractor/Handler/JmsSecurityExtraSecureHandler.php +++ b/Extractor/Handler/JmsSecurityExtraHandler.php @@ -12,13 +12,14 @@ namespace Nelmio\ApiDocBundle\Extractor\Handler; use Nelmio\ApiDocBundle\Extractor\HandlerInterface; -use \Nelmio\ApiDocBundle\Annotation\ApiDoc; +use Nelmio\ApiDocBundle\Annotation\ApiDoc; +use Symfony\Component\Routing\Route; -class JmsSecurityExtraSecureHandler implements HandlerInterface +class JmsSecurityExtraHandler implements HandlerInterface { const JMS_SECURITY_EXTRA_SECURE_CLASS = 'JMS\\SecurityExtraBundle\\Annotation\\Secure'; - public function handle(ApiDoc $annotation, $annotations) + public function handle(ApiDoc $annotation, $annotations, Route $route, \ReflectionMethod $method) { foreach ($annotations as $annot) { if (is_a($annot, self::JMS_SECURITY_EXTRA_SECURE_CLASS)) { diff --git a/Extractor/Handler/SensioFrameworkExtraCacheHandler.php b/Extractor/Handler/SensioFrameworkExtraHandler.php similarity index 72% rename from Extractor/Handler/SensioFrameworkExtraCacheHandler.php rename to Extractor/Handler/SensioFrameworkExtraHandler.php index 1b22d86..e92f143 100644 --- a/Extractor/Handler/SensioFrameworkExtraCacheHandler.php +++ b/Extractor/Handler/SensioFrameworkExtraHandler.php @@ -12,13 +12,14 @@ namespace Nelmio\ApiDocBundle\Extractor\Handler; use Nelmio\ApiDocBundle\Extractor\HandlerInterface; -use \Nelmio\ApiDocBundle\Annotation\ApiDoc; +use Nelmio\ApiDocBundle\Annotation\ApiDoc; +use Symfony\Component\Routing\Route; -class SensioFrameworkExtraCacheHandler implements HandlerInterface +class SensioFrameworkExtraHandler implements HandlerInterface { const CACHE_ANNOTATION_CLASS = 'Sensio\\Bundle\\FrameworkExtraBundle\\Configuration\\Cache'; - public function handle(ApiDoc $annotation, $annotations) + public function handle(ApiDoc $annotation, $annotations, Route $route, \ReflectionMethod $method) { foreach ($annotations as $annot) { if (is_a($annot, self::CACHE_ANNOTATION_CLASS)) { diff --git a/Extractor/HandlerInterface.php b/Extractor/HandlerInterface.php index bedf2ff..00557e1 100644 --- a/Extractor/HandlerInterface.php +++ b/Extractor/HandlerInterface.php @@ -13,7 +13,9 @@ namespace Nelmio\ApiDocBundle\Extractor; use Nelmio\ApiDocBundle\Annotation\ApiDoc; +use Symfony\Component\Routing\Route; + interface HandlerInterface { - public function handle(ApiDoc $annotation, $annotations); + public function handle(ApiDoc $annotation, $annotations, Route $route, \ReflectionMethod $method); } diff --git a/NelmioApiDocBundle.php b/NelmioApiDocBundle.php index ad9a5ce..c165888 100644 --- a/NelmioApiDocBundle.php +++ b/NelmioApiDocBundle.php @@ -6,6 +6,7 @@ use Symfony\Component\HttpKernel\Bundle\Bundle; use Symfony\Component\DependencyInjection\ContainerBuilder; use Nelmio\ApiDocBundle\DependencyInjection\RegisterJmsParserPass; use Nelmio\ApiDocBundle\DependencyInjection\RegisterExtractorParsersPass; +use Nelmio\ApiDocBundle\DependencyInjection\ExtractorHandlerCompilerPass; class NelmioApiDocBundle extends Bundle { @@ -15,5 +16,6 @@ class NelmioApiDocBundle extends Bundle $container->addCompilerPass(new RegisterJmsParserPass()); $container->addCompilerPass(new RegisterExtractorParsersPass()); + $container->addCompilerPass(new ExtractorHandlerCompilerPass()); } } diff --git a/Resources/config/services.xml b/Resources/config/services.xml index c53998c..2c15d31 100644 --- a/Resources/config/services.xml +++ b/Resources/config/services.xml @@ -9,10 +9,9 @@ Nelmio\ApiDocBundle\Twig\Extension\MarkdownExtension Nelmio\ApiDocBundle\Util\DocCommentExtractor - Nelmio\ApiDocBundle\Extractor\Handler\FosRestQueryParamHandler - Nelmio\ApiDocBundle\Extractor\Handler\FosRestRequestParamHandler - Nelmio\ApiDocBundle\Extractor\Handler\JmsSecurityExtraSecureHandler - Nelmio\ApiDocBundle\Extractor\Handler\SensioFrameworkExtraCacheHandler + Nelmio\ApiDocBundle\Extractor\Handler\FosRestHandler + Nelmio\ApiDocBundle\Extractor\Handler\JmsSecurityExtraHandler + Nelmio\ApiDocBundle\Extractor\Handler\SensioFrameworkExtraHandler @@ -36,19 +35,15 @@ - + - + - - - - - + From 7f79ddc065f64da23069787432801e0be30bcfa7 Mon Sep 17 00:00:00 2001 From: fvilpoix Date: Wed, 17 Apr 2013 13:41:28 +0200 Subject: [PATCH 3/4] [ExtractorHandler] cleaning code --- DependencyInjection/NelmioApiDocExtension.php | 1 - Extractor/Handler/FosRestHandler.php | 9 ++++----- Extractor/Handler/JmsSecurityExtraHandler.php | 5 ++--- Extractor/Handler/SensioFrameworkExtraHandler.php | 5 ++--- Extractor/HandlerInterface.php | 8 ++++++++ README.md | 4 +++- 6 files changed, 19 insertions(+), 13 deletions(-) diff --git a/DependencyInjection/NelmioApiDocExtension.php b/DependencyInjection/NelmioApiDocExtension.php index 6298f78..ce10263 100644 --- a/DependencyInjection/NelmioApiDocExtension.php +++ b/DependencyInjection/NelmioApiDocExtension.php @@ -16,7 +16,6 @@ use Symfony\Component\DependencyInjection\Loader\XmlFileLoader; use Symfony\Component\DependencyInjection\ContainerBuilder; use Symfony\Component\Config\Definition\Processor; use Symfony\Component\Config\FileLocator; -use Symfony\Component\DependencyInjection\Reference; class NelmioApiDocExtension extends Extension { diff --git a/Extractor/Handler/FosRestHandler.php b/Extractor/Handler/FosRestHandler.php index 8ad2602..a3b3373 100644 --- a/Extractor/Handler/FosRestHandler.php +++ b/Extractor/Handler/FosRestHandler.php @@ -14,23 +14,22 @@ namespace Nelmio\ApiDocBundle\Extractor\Handler; use Nelmio\ApiDocBundle\Extractor\HandlerInterface; use Nelmio\ApiDocBundle\Annotation\ApiDoc; use Symfony\Component\Routing\Route; +use FOS\RestBundle\Controller\Annotations\RequestParam; +use FOS\RestBundle\Controller\Annotations\QueryParam; class FosRestHandler implements HandlerInterface { - const FOS_REST_REQUEST_PARAM_CLASS = 'FOS\\RestBundle\\Controller\\Annotations\\RequestParam'; - const FOS_REST_QUERY_PARAM_CLASS = 'FOS\\RestBundle\\Controller\\Annotations\\QueryParam'; - public function handle(ApiDoc $annotation, $annotations, Route $route, \ReflectionMethod $method) { foreach ($annotations as $annot) { - if (is_a($annot, self::FOS_REST_REQUEST_PARAM_CLASS)) { + if ($annot instanceof RequestParam) { $annotation->addParameter($annot->name, array( 'required' => $annot->strict && $annot->default === null, 'dataType' => $annot->requirements, 'description' => $annot->description, 'readonly' => false )); - } elseif (is_a($annot, self::FOS_REST_QUERY_PARAM_CLASS)) { + } elseif ($annot instanceof QueryParam) { if ($annot->strict && $annot->default === null) { $annotation->addRequirement($annot->name, array( 'requirement' => $annot->requirements, diff --git a/Extractor/Handler/JmsSecurityExtraHandler.php b/Extractor/Handler/JmsSecurityExtraHandler.php index 6dfca7a..2c639b4 100644 --- a/Extractor/Handler/JmsSecurityExtraHandler.php +++ b/Extractor/Handler/JmsSecurityExtraHandler.php @@ -14,15 +14,14 @@ namespace Nelmio\ApiDocBundle\Extractor\Handler; use Nelmio\ApiDocBundle\Extractor\HandlerInterface; use Nelmio\ApiDocBundle\Annotation\ApiDoc; use Symfony\Component\Routing\Route; +use JMS\SecurityExtraBundle\Annotation\Secure; class JmsSecurityExtraHandler implements HandlerInterface { - const JMS_SECURITY_EXTRA_SECURE_CLASS = 'JMS\\SecurityExtraBundle\\Annotation\\Secure'; - public function handle(ApiDoc $annotation, $annotations, Route $route, \ReflectionMethod $method) { foreach ($annotations as $annot) { - if (is_a($annot, self::JMS_SECURITY_EXTRA_SECURE_CLASS)) { + if ($annot instanceof Secure) { $annotation->setAuthentication(true); } } diff --git a/Extractor/Handler/SensioFrameworkExtraHandler.php b/Extractor/Handler/SensioFrameworkExtraHandler.php index e92f143..55eac5c 100644 --- a/Extractor/Handler/SensioFrameworkExtraHandler.php +++ b/Extractor/Handler/SensioFrameworkExtraHandler.php @@ -14,15 +14,14 @@ namespace Nelmio\ApiDocBundle\Extractor\Handler; use Nelmio\ApiDocBundle\Extractor\HandlerInterface; use Nelmio\ApiDocBundle\Annotation\ApiDoc; use Symfony\Component\Routing\Route; +use Sensio\Bundle\FrameworkExtraBundle\Configuration\Cache; class SensioFrameworkExtraHandler implements HandlerInterface { - const CACHE_ANNOTATION_CLASS = 'Sensio\\Bundle\\FrameworkExtraBundle\\Configuration\\Cache'; - public function handle(ApiDoc $annotation, $annotations, Route $route, \ReflectionMethod $method) { foreach ($annotations as $annot) { - if (is_a($annot, self::CACHE_ANNOTATION_CLASS)) { + if ($annot instanceof Cache) { $annotation->setCache($annot->getMaxAge()); } } diff --git a/Extractor/HandlerInterface.php b/Extractor/HandlerInterface.php index 00557e1..ae2f475 100644 --- a/Extractor/HandlerInterface.php +++ b/Extractor/HandlerInterface.php @@ -17,5 +17,13 @@ use Symfony\Component\Routing\Route; interface HandlerInterface { + /** + * Parse route parameters in order to populate ApiDoc. + * + * @param Nelmio\ApiDocBundle\Annotation\ApiDoc $annotation + * @param array $annotations + * @param Symfony\Component\Routing\Route $route + * @param ReflectionMethod $method + */ public function handle(ApiDoc $annotation, $annotations, Route $route, \ReflectionMethod $method); } diff --git a/README.md b/README.md index a146aa2..13ba96e 100644 --- a/README.md +++ b/README.md @@ -238,7 +238,9 @@ You can also define your own motd content (above methods list). All you have to ## Using your own annotations ## -If you have developped your own project-related annotations, and you want to parse them to populate the ApiDoc, you can provide custom handlers as services. You juste have to implements the `Nelmio\ApiDocBundle\Extractor\HandlerInterface` and tag it as `nelmio_api_doc.extractor.handler`. +If you have developped your own project-related annotations, and you want to parse them to populate the ApiDoc, +you can provide custom handlers as services. You juste have to implements the +`Nelmio\ApiDocBundle\Extractor\HandlerInterface` and tag it as `nelmio_api_doc.extractor.handler`. #app/config/config.yml services: From 3e04cbfdf1a1cd7981446f051d3ba0f521675e3c Mon Sep 17 00:00:00 2001 From: fvilpoix Date: Wed, 17 Apr 2013 14:24:45 +0200 Subject: [PATCH 4/4] [ExtractorHandler] code cleaning --- Extractor/Handler/FosRestHandler.php | 2 +- Extractor/Handler/JmsSecurityExtraHandler.php | 2 +- Extractor/Handler/SensioFrameworkExtraHandler.php | 2 +- Extractor/HandlerInterface.php | 3 +-- 4 files changed, 4 insertions(+), 5 deletions(-) diff --git a/Extractor/Handler/FosRestHandler.php b/Extractor/Handler/FosRestHandler.php index a3b3373..cb394b1 100644 --- a/Extractor/Handler/FosRestHandler.php +++ b/Extractor/Handler/FosRestHandler.php @@ -19,7 +19,7 @@ use FOS\RestBundle\Controller\Annotations\QueryParam; class FosRestHandler implements HandlerInterface { - public function handle(ApiDoc $annotation, $annotations, Route $route, \ReflectionMethod $method) + public function handle(ApiDoc $annotation, array $annotations, Route $route, \ReflectionMethod $method) { foreach ($annotations as $annot) { if ($annot instanceof RequestParam) { diff --git a/Extractor/Handler/JmsSecurityExtraHandler.php b/Extractor/Handler/JmsSecurityExtraHandler.php index 2c639b4..87dfdc2 100644 --- a/Extractor/Handler/JmsSecurityExtraHandler.php +++ b/Extractor/Handler/JmsSecurityExtraHandler.php @@ -18,7 +18,7 @@ use JMS\SecurityExtraBundle\Annotation\Secure; class JmsSecurityExtraHandler implements HandlerInterface { - public function handle(ApiDoc $annotation, $annotations, Route $route, \ReflectionMethod $method) + public function handle(ApiDoc $annotation, array $annotations, Route $route, \ReflectionMethod $method) { foreach ($annotations as $annot) { if ($annot instanceof Secure) { diff --git a/Extractor/Handler/SensioFrameworkExtraHandler.php b/Extractor/Handler/SensioFrameworkExtraHandler.php index 55eac5c..5e5afc9 100644 --- a/Extractor/Handler/SensioFrameworkExtraHandler.php +++ b/Extractor/Handler/SensioFrameworkExtraHandler.php @@ -18,7 +18,7 @@ use Sensio\Bundle\FrameworkExtraBundle\Configuration\Cache; class SensioFrameworkExtraHandler implements HandlerInterface { - public function handle(ApiDoc $annotation, $annotations, Route $route, \ReflectionMethod $method) + public function handle(ApiDoc $annotation, array $annotations, Route $route, \ReflectionMethod $method) { foreach ($annotations as $annot) { if ($annot instanceof Cache) { diff --git a/Extractor/HandlerInterface.php b/Extractor/HandlerInterface.php index ae2f475..37a5e74 100644 --- a/Extractor/HandlerInterface.php +++ b/Extractor/HandlerInterface.php @@ -12,7 +12,6 @@ namespace Nelmio\ApiDocBundle\Extractor; use Nelmio\ApiDocBundle\Annotation\ApiDoc; - use Symfony\Component\Routing\Route; interface HandlerInterface @@ -25,5 +24,5 @@ interface HandlerInterface * @param Symfony\Component\Routing\Route $route * @param ReflectionMethod $method */ - public function handle(ApiDoc $annotation, $annotations, Route $route, \ReflectionMethod $method); + public function handle(ApiDoc $annotation, array $annotations, Route $route, \ReflectionMethod $method); }