Moving annotation extraction into tagged Handlers

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

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

Extractor/Handler/EmptyHandler.php

@@ -0,0 +1,22 @@
+<?php
+
+/*
+ * This file is part of the NelmioApiDocBundle.
+ *
+ * (c) Nelmio <hello@nelm.io>
+ *
+ * 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)
+    {
+    }
+}

Extractor/Handler/FosRestQueryParamHandler.php

@@ -0,0 +1,40 @@
+<?php
+
+/*
+ * This file is part of the NelmioApiDocBundle.
+ *
+ * (c) Nelmio <hello@nelm.io>
+ *
+ * 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,
+                    ));
+                }
+            }
+        }
+    }
+}

Extractor/Handler/FosRestRequestParamHandler.php

@@ -0,0 +1,34 @@
+<?php
+
+/*
+ * This file is part of the NelmioApiDocBundle.
+ *
+ * (c) Nelmio <hello@nelm.io>
+ *
+ * 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
+                ));
+            }
+        }
+    }
+}

Extractor/Handler/JmsSecurityExtraSecureHandler.php

@@ -0,0 +1,29 @@
+<?php
+
+/*
+ * This file is part of the NelmioApiDocBundle.
+ *
+ * (c) Nelmio <hello@nelm.io>
+ *
+ * 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);
+            }
+        }
+    }
+}

Extractor/Handler/SensioFrameworkExtraCacheHandler.php

@@ -0,0 +1,29 @@
+<?php
+
+/*
+ * This file is part of the NelmioApiDocBundle.
+ *
+ * (c) Nelmio <hello@nelm.io>
+ *
+ * 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());
+            }
+        }
+    }
+}

Extractor/HandlerInterface.php

@@ -0,0 +1,19 @@
+<?php
+
+/*
+ * This file is part of the NelmioApiDocBundle.
+ *
+ * (c) Nelmio <hello@nelm.io>
+ *
+ * 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);
+}

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.

Resources/config/services.xml

@@ -8,6 +8,11 @@
         <parameter key="nelmio_api_doc.form.extension.description_form_type_extension.class">Nelmio\ApiDocBundle\Form\Extension\DescriptionFormTypeExtension</parameter>
         <parameter key="nelmio_api_doc.twig.extension.extra_markdown.class">Nelmio\ApiDocBundle\Twig\Extension\MarkdownExtension</parameter>
         <parameter key="nelmio_api_doc.doc_comment_extractor.class">Nelmio\ApiDocBundle\Util\DocCommentExtractor</parameter>
+
+        <parameter key="nelmio_api_doc.extractor.handler.fos_rest_query_param.class">Nelmio\ApiDocBundle\Extractor\Handler\FosRestQueryParamHandler</parameter>
+        <parameter key="nelmio_api_doc.extractor.handler.fos_rest_request_param.class">Nelmio\ApiDocBundle\Extractor\Handler\FosRestRequestParamHandler</parameter>
+        <parameter key="nelmio_api_doc.extractor.handler.jms_security_secure.class">Nelmio\ApiDocBundle\Extractor\Handler\JmsSecurityExtraSecureHandler</parameter>
+        <parameter key="nelmio_api_doc.extractor.handler.sensio_cache.class">Nelmio\ApiDocBundle\Extractor\Handler\SensioFrameworkExtraCacheHandler</parameter>
     </parameters>
 
     <services>
@@ -18,6 +23,7 @@
             <argument type="service" id="router" />
             <argument type="service" id="annotation_reader" />
             <argument type="service" id="nelmio_api_doc.doc_comment_extractor" />
+            <argument type="collection"/>
         </service>
 
         <service id="nelmio_api_doc.form.extension.description_form_type_extension" class="%nelmio_api_doc.form.extension.description_form_type_extension.class%">
@@ -27,6 +33,25 @@
         <service id="nelmio_api_doc.twig.extension.extra_markdown" class="%nelmio_api_doc.twig.extension.extra_markdown.class%">
             <tag name="twig.extension" />
         </service>
+
+        <!-- Extractor Annotation Handlers -->
+
+        <service id="nelmio_api_doc.extractor.handler.fos_rest_query_param" class="%nelmio_api_doc.extractor.handler.fos_rest_query_param.class%">
+            <tag name="nelmio_api_doc.extractor.handler"/>
+        </service>
+
+        <service id="nelmio_api_doc.extractor.handler.fos_rest_request_param" class="%nelmio_api_doc.extractor.handler.fos_rest_request_param.class%">
+            <tag name="nelmio_api_doc.extractor.handler"/>
+        </service>
+
+        <service id="nelmio_api_doc.extractor.handler.jms_security_secure" class="%nelmio_api_doc.extractor.handler.jms_security_secure.class%">
+            <tag name="nelmio_api_doc.extractor.handler"/>
+        </service>
+
+        <service id="nelmio_api_doc.extractor.handler.sension_cache" class="%nelmio_api_doc.extractor.handler.sensio_cache.class%">
+            <tag name="nelmio_api_doc.extractor.handler"/>
+        </service>
+
     </services>
 
 </container>