allow users to use inspectors to further analyse the annotations

src/System/OpenApiAnalyser.php

@@ -9,7 +9,9 @@
 use OpenApi\Annotations\Operation;
 use OpenApi\Attributes\Middleware;
 use OpenApi\Context;
+use Override;
 use Zrnik\AttributeReflection\AttributeReflection;
+use Zrnik\Zweist\ZweistConfiguration;
 use Zrnik\Zweist\ZweistRouteService;
 
 /**
@@ -20,16 +22,17 @@ class OpenApiAnalyser extends Analysis
     /** @phpstan-var SlimRouteDataArrayShape[] */
     private array $routes = [];
 
-    public function __construct()
+    public function __construct(
+        private readonly ZweistConfiguration $zweistConfiguration
+    )
     {
         parent::__construct([], new Context());
     }
 
-    #[\Override]
+    #[Override]
     public function addAnnotation(object $annotation, Context $context): void
     {
         if ($annotation instanceof Operation) {
-
             /** @var class-string $controllerClass */
             $controllerClass = sprintf(
                 '%s\%s',
@@ -64,6 +67,10 @@ public function addAnnotation(object $annotation, Context $context): void
                 'controller_method' => $method,
                 'middleware' => $middleware,
             ];
+
+            foreach ($this->zweistConfiguration->inspectors as $inspector) {
+                $inspector->inspect($controllerClass, $method, $annotation);
+            }
         }
 
         parent::addAnnotation($annotation, $context);

src/System/OpenApiInspector.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Zrnik\Zweist\System;
+
+use OpenApi\Annotations\AbstractAnnotation;
+
+interface OpenApiInspector
+{
+    /**
+     * @param class-string $className
+     * @param string $methodName
+     * @param AbstractAnnotation $annotation
+     * @return void
+     */
+    public function inspect(string $className, string $methodName, AbstractAnnotation $annotation): void;
+}

src/ZweistConfiguration.php

@@ -5,6 +5,7 @@
 namespace Zrnik\Zweist;
 
 use Zrnik\Zweist\Exception\MisconfiguredOpenApiGeneratorException;
+use Zrnik\Zweist\System\OpenApiInspector;
 
 class ZweistConfiguration
 {
@@ -15,11 +16,13 @@ class ZweistConfiguration
 
     /**
      * @param string[] $openApiDefinitionPaths
+     * @param OpenApiInspector[] $inspectors
      */
     public function __construct(
         array $openApiDefinitionPaths,
         public readonly string $openApiJsonPath,
         public readonly string $routerJsonPath,
+        public readonly array $inspectors = [],
     )
     {
         if (count($openApiDefinitionPaths) === 0) {

src/ZweistOpenApiGenerator.php

@@ -31,7 +31,7 @@ public function __construct(
      */
     public function generate(): void
     {
-        $openApiAnalyser = new OpenApiAnalyser();
+        $openApiAnalyser = new OpenApiAnalyser($this->zweistConfiguration);
 
         $openApi = Generator::scan(
             $this->zweistConfiguration->openApiDefinitionPaths,

tests/ExampleApplication/ExampleInspector.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Zrnik\Zweist\Tests\ExampleApplication;
+
+use Exception;
+use OpenApi\Annotations\AbstractAnnotation;
+use Zrnik\Zweist\System\OpenApiInspector;
+
+class ExampleInspector implements OpenApiInspector
+{
+    /**
+     * @throws Exception
+     */
+    public function inspect(string $className, string $methodName, AbstractAnnotation $annotation): void
+    {
+        /**
+         * @noinspection ThrowRawExceptionInspection
+         */
+        throw new Exception(sprintf('%s called', self::class));
+    }
+}

tests/InspectorTest.php

@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Zrnik\Zweist\Tests;
+
+use DI\Container;
+use Exception;
+use PHPUnit\Framework\TestCase;
+use Psr\Log\LoggerInterface;
+use Zrnik\PHPUnit\Exceptions;
+use Zrnik\Zweist\Tests\ExampleApplication\ExampleInspector;
+use Zrnik\Zweist\ZweistConfiguration;
+use Zrnik\Zweist\ZweistOpenApiGenerator;
+
+class InspectorTest extends TestCase
+{
+    use Exceptions;
+
+    private Container $container;
+
+    private ZweistConfiguration $zweistConfiguration;
+
+    /**
+     * @throws Exception
+     */
+    protected function setUp(): void
+    {
+        $this->container = new Container();
+
+        $this->container->set(LoggerInterface::class, $this->createMock(LoggerInterface::class));
+
+        $this->zweistConfiguration = new ZweistConfiguration(
+            [
+                __DIR__ . '/ExampleApplication',
+            ],
+            __DIR__ . '/../temp/OpenApi.json',
+            __DIR__ . '/../temp/router.json',
+            [
+                new ExampleInspector(),
+            ],
+        );
+    }
+
+    public function testInspectorCalled(): void
+    {
+        $zweistOpenApiGenerator = new ZweistOpenApiGenerator($this->zweistConfiguration, $this->container);
+
+        /** @var Exception $exception */
+        $exception = $this->assertExceptionThrown(
+            Exception::class,
+            fn() => $zweistOpenApiGenerator->generate(),
+        );
+
+        $this->assertSame(sprintf('%s called', ExampleInspector::class), $exception->getMessage());
+    }
+}