Merge pull request #23 from retailcrm/attribute

Migrate annotation ApiDoc to attribute
retailcrm · Oct 1, 2024 · a896abb · a896abb
2 parents 8135dec + a9fceca
commit a896abb
Show file tree

Hide file tree

Showing 21 changed files with 372 additions and 599 deletions.
diff --git a/Annotation/ApiDoc.php → Attribute/ApiDoc.php b/Annotation/ApiDoc.php → Attribute/ApiDoc.php
diff --git a/Command/DumpCommand.php b/Command/DumpCommand.php
@@ -11,7 +11,7 @@
 
 namespace Nelmio\ApiDocBundle\Command;
 
-use Nelmio\ApiDocBundle\Annotation\ApiDoc;
+use Nelmio\ApiDocBundle\Attribute\ApiDoc;
 use Nelmio\ApiDocBundle\Extractor\ApiDocExtractor;
 use Nelmio\ApiDocBundle\Formatter\HtmlFormatter;
 use Nelmio\ApiDocBundle\Formatter\MarkdownFormatter;

diff --git a/Controller/ApiDocController.php b/Controller/ApiDocController.php
@@ -11,7 +11,7 @@
 
 namespace Nelmio\ApiDocBundle\Controller;
 
-use Nelmio\ApiDocBundle\Annotation\ApiDoc;
+use Nelmio\ApiDocBundle\Attribute\ApiDoc;
 use Nelmio\ApiDocBundle\Extractor\ApiDocExtractor;
 use Nelmio\ApiDocBundle\Formatter\HtmlFormatter;
 use Nelmio\ApiDocBundle\Formatter\RequestAwareSwaggerFormatter;

diff --git a/DependencyInjection/ExtractorHandlerCompilerPass.php b/DependencyInjection/ExtractorHandlerCompilerPass.php
@@ -26,7 +26,7 @@ public function process(ContainerBuilder $container): void
 
         $container
             ->getDefinition('nelmio_api_doc.extractor.api_doc_extractor')
-            ->replaceArgument(3, $handlers)
+            ->replaceArgument(2, $handlers)
         ;
     }
 }
diff --git a/Extractor/ApiDocExtractor.php b/Extractor/ApiDocExtractor.php
@@ -11,8 +11,7 @@
 
 namespace Nelmio\ApiDocBundle\Extractor;
 
-use Doctrine\Common\Annotations\Reader;
-use Nelmio\ApiDocBundle\Annotation\ApiDoc;
+use Nelmio\ApiDocBundle\Attribute\ApiDoc;
 use Nelmio\ApiDocBundle\DataTypes;
 use Nelmio\ApiDocBundle\Parser\ParserInterface;
 use Nelmio\ApiDocBundle\Parser\PostParserInterface;
@@ -22,8 +21,6 @@
 
 class ApiDocExtractor
 {
-    public const ANNOTATION_CLASS = ApiDoc::class;
-
     /**
      * @var ParserInterface[]
      */
@@ -35,7 +32,6 @@ class ApiDocExtractor
      */
     public function __construct(
         protected RouterInterface $router,
-        protected Reader $reader,
         protected DocCommentExtractor $commentExtractor,
         protected array $handlers,
         protected array $excludeSections,
@@ -49,17 +45,15 @@ public function __construct(
      *
      * @return Route[] An array of routes
      */
-    public function getRoutes()
+    public function getRoutes(): array
     {
         return $this->router->getRouteCollection()->all();
     }
 
-    /**
+    /*
      * Extracts annotations from all known routes
-     *
-     * @return array
      */
-    public function all($view = ApiDoc::DEFAULT_VIEW)
+    public function all($view = ApiDoc::DEFAULT_VIEW): array
     {
         return $this->extractAnnotations($this->getRoutes(), $view);
     }
@@ -69,10 +63,8 @@ public function all($view = ApiDoc::DEFAULT_VIEW)
      *
      * @param string $apiVersion API version
      * @param string $view
-     *
-     * @return array
      */
-    public function allForVersion($apiVersion, $view = ApiDoc::DEFAULT_VIEW)
+    public function allForVersion($apiVersion, $view = ApiDoc::DEFAULT_VIEW): array
     {
         $data = $this->all($view);
         foreach ($data as $k => $a) {
@@ -94,10 +86,8 @@ public function allForVersion($apiVersion, $view = ApiDoc::DEFAULT_VIEW)
      *  - resource
      *
      * @param array $routes array of Route-objects for which the annotations should be extracted
-     *
-     * @return array
      */
-    public function extractAnnotations(array $routes, $view = ApiDoc::DEFAULT_VIEW)
+    public function extractAnnotations(array $routes, $view = ApiDoc::DEFAULT_VIEW): array
     {
         $array = [];
         $resources = [];
@@ -108,7 +98,7 @@ public function extractAnnotations(array $routes, $view = ApiDoc::DEFAULT_VIEW)
             }
 
             if ($method = $this->getReflectionMethod($route->getDefault('_controller'))) {
-                $annotation = $this->reader->getMethodAnnotation($method, static::ANNOTATION_CLASS);
+                $annotation = $this->getMethodApiDoc($method);
                 if (
                     $annotation && !in_array($annotation->getSection(), $this->excludeSections)
                     && (in_array($view, $annotation->getViews()) || (0 === count($annotation->getViews()) && ApiDoc::DEFAULT_VIEW === $view))
@@ -214,7 +204,7 @@ public function getReflectionMethod($controller)
     public function get($controller, $route)
     {
         if ($method = $this->getReflectionMethod($controller)) {
-            if ($annotation = $this->reader->getMethodAnnotation($method, static::ANNOTATION_CLASS)) {
+            if ($annotation = $this->getMethodApiDoc($method)) {
                 if ($route = $this->router->getRouteCollection()->get($route)) {
                     return $this->extractData($annotation, $route, $method);
                 }
@@ -224,6 +214,16 @@ public function get($controller, $route)
         return null;
     }
 
+    protected function getMethodApiDoc(\ReflectionMethod $method): ?ApiDoc
+    {
+        $attributes = $method->getAttributes(ApiDoc::class, \ReflectionAttribute::IS_INSTANCEOF);
+        if (!$attributes) {
+            return null;
+        }
+
+        return $attributes[0]->newInstance();
+    }
+
     /**
      * Registers a class parser to use for parsing input class metadata
      */
@@ -444,13 +444,13 @@ protected function mergeParameters($p1, $p2)
                     } elseif (null !== $value) {
                         if (in_array($name, ['required', 'readonly'])) {
                             $v1[$name] = $v1[$name] || $value;
-                        } elseif (in_array($name, ['requirement'])) {
+                        } elseif ('requirement' === $name) {
                             if (isset($v1[$name])) {
                                 $v1[$name] .= ', ' . $value;
                             } else {
                                 $v1[$name] = $value;
                             }
-                        } elseif ('default' == $name) {
+                        } elseif ('default' === $name) {
                             if (isset($v1[$name])) {
                                 $v1[$name] = $value ?? $v1[$name];
                             } else {
@@ -472,8 +472,6 @@ protected function mergeParameters($p1, $p2)
     /**
      * Parses annotations for a given method, and adds new information to the given ApiDoc
      * annotation. Useful to extract information from the FOSRestBundle annotations.
-     *
-     * @param ReflectionMethod $method
      */
     protected function parseAnnotations(ApiDoc $annotation, Route $route, \ReflectionMethod $method): void
     {

diff --git a/Extractor/CachingApiDocExtractor.php b/Extractor/CachingApiDocExtractor.php
@@ -11,8 +11,7 @@
 
 namespace Nelmio\ApiDocBundle\Extractor;
 
-use Doctrine\Common\Annotations\Reader;
-use Nelmio\ApiDocBundle\Annotation\ApiDoc;
+use Nelmio\ApiDocBundle\Attribute\ApiDoc;
 use Nelmio\ApiDocBundle\Util\DocCommentExtractor;
 use Symfony\Component\Config\ConfigCache;
 use Symfony\Component\Config\Resource\FileResource;
@@ -32,30 +31,31 @@ class CachingApiDocExtractor extends ApiDocExtractor
      */
     public function __construct(
         RouterInterface $router,
-        Reader $reader,
         DocCommentExtractor $commentExtractor,
         array $handlers,
         array $excludeSections,
         private string $cacheFile,
         private bool $debug = false,
     ) {
-        parent::__construct($router, $reader, $commentExtractor, $handlers, $excludeSections);
+        parent::__construct($router, $commentExtractor, $handlers, $excludeSections);
     }
 
     /**
      * @param string $view View name
      *
      * @return array|mixed
      */
-    public function all($view = ApiDoc::DEFAULT_VIEW)
+    public function all($view = ApiDoc::DEFAULT_VIEW): array
     {
         $cache = $this->getViewCache($view);
 
         if (!$cache->isFresh()) {
             $resources = [];
             foreach ($this->getRoutes() as $route) {
-                if (null !== ($method = $this->getReflectionMethod($route->getDefault('_controller')))
-                  && null !== ($annotation = $this->reader->getMethodAnnotation($method, self::ANNOTATION_CLASS))) {
+                if (
+                    null !== ($method = $this->getReflectionMethod($route->getDefault('_controller')))
+                    && null !== $this->getMethodApiDoc($method)
+                ) {
                     $file = $method->getDeclaringClass()->getFileName();
                     $resources[] = new FileResource($file);
                 }

diff --git a/Extractor/Handler/PhpDocHandler.php b/Extractor/Handler/PhpDocHandler.php
@@ -11,7 +11,7 @@
 
 namespace Nelmio\ApiDocBundle\Extractor\Handler;
 
-use Nelmio\ApiDocBundle\Annotation\ApiDoc;
+use Nelmio\ApiDocBundle\Attribute\ApiDoc;
 use Nelmio\ApiDocBundle\Extractor\HandlerInterface;
 use Nelmio\ApiDocBundle\Util\DocCommentExtractor;
 use Symfony\Component\Routing\Route;
@@ -74,7 +74,7 @@ public function handle(ApiDoc $annotation, Route $route, \ReflectionMethod $meth
             $found = false;
             foreach ($paramDocs as $paramDoc) {
                 if (preg_match(sprintf($regexp, preg_quote($var)), $paramDoc, $matches)) {
-                    $annotationRequirements = $annotation->getrequirements();
+                    $annotationRequirements = $annotation->getRequirements();
 
                     if (!isset($annotationRequirements[$var]['dataType'])) {
                         $requirements[$var]['dataType'] = $matches[1] ?? '';

diff --git a/Extractor/HandlerInterface.php b/Extractor/HandlerInterface.php
@@ -11,7 +11,7 @@
 
 namespace Nelmio\ApiDocBundle\Extractor;
 
-use Nelmio\ApiDocBundle\Annotation\ApiDoc;
+use Nelmio\ApiDocBundle\Attribute\ApiDoc;
 use Symfony\Component\Routing\Route;
 
 interface HandlerInterface

diff --git a/Formatter/AbstractFormatter.php b/Formatter/AbstractFormatter.php
@@ -11,7 +11,7 @@
 
 namespace Nelmio\ApiDocBundle\Formatter;
 
-use Nelmio\ApiDocBundle\Annotation\ApiDoc;
+use Nelmio\ApiDocBundle\Attribute\ApiDoc;
 use Nelmio\ApiDocBundle\DataTypes;
 
 abstract class AbstractFormatter implements FormatterInterface

diff --git a/Formatter/FormatterInterface.php b/Formatter/FormatterInterface.php
@@ -11,7 +11,7 @@
 
 namespace Nelmio\ApiDocBundle\Formatter;
 
-use Nelmio\ApiDocBundle\Annotation\ApiDoc;
+use Nelmio\ApiDocBundle\Attribute\ApiDoc;
 
 interface FormatterInterface
 {

diff --git a/Formatter/RequestAwareSwaggerFormatter.php b/Formatter/RequestAwareSwaggerFormatter.php
@@ -11,7 +11,7 @@
 
 namespace Nelmio\ApiDocBundle\Formatter;
 
-use Nelmio\ApiDocBundle\Annotation\ApiDoc;
+use Nelmio\ApiDocBundle\Attribute\ApiDoc;
 use Symfony\Component\HttpFoundation\Request;
 
 /**

diff --git a/Formatter/SimpleFormatter.php b/Formatter/SimpleFormatter.php
@@ -11,7 +11,7 @@
 
 namespace Nelmio\ApiDocBundle\Formatter;
 
-use Nelmio\ApiDocBundle\Annotation\ApiDoc;
+use Nelmio\ApiDocBundle\Attribute\ApiDoc;
 
 class SimpleFormatter extends AbstractFormatter
 {

diff --git a/Formatter/SwaggerFormatter.php b/Formatter/SwaggerFormatter.php
@@ -11,7 +11,7 @@
 
 namespace Nelmio\ApiDocBundle\Formatter;
 
-use Nelmio\ApiDocBundle\Annotation\ApiDoc;
+use Nelmio\ApiDocBundle\Attribute\ApiDoc;
 use Nelmio\ApiDocBundle\DataTypes;
 use Nelmio\ApiDocBundle\Swagger\ModelRegistry;
 use Symfony\Component\HttpFoundation\Response;

diff --git a/Resources/config/services.xml b/Resources/config/services.xml
@@ -25,7 +25,6 @@
 
         <service id="nelmio_api_doc.extractor.api_doc_extractor" class="%nelmio_api_doc.extractor.api_doc_extractor.class%" public="true">
             <argument type="service" id="router" />
-            <argument type="service" id="annotation_reader" />
             <argument type="service" id="nelmio_api_doc.doc_comment_extractor" />
             <argument type="collection" />
             <argument>%nelmio_api_doc.exclude_sections%</argument>

diff --git a/Resources/doc/the-apidoc-annotation.rst b/Resources/doc/the-apidoc-annotation.rst
@@ -5,7 +5,7 @@ The bundle provides an ``ApiDoc()`` annotation for your controllers::
 
     namespace Your\Namespace;
 
-    use Nelmio\ApiDocBundle\Annotation\ApiDoc;
+    use Nelmio\ApiDocBundle\Attribute\ApiDoc;
 
     class YourController extends Controller
     {