Merge remote-tracking branch 'origin/master'

.doctor-rst.yaml

@@ -53,10 +53,10 @@ rules:
 
     #   master
     versionadded_directive_major_version:
-        major_version: 5
+        major_version: 6
 
     versionadded_directive_min_version:
-        min_version: '5.0'
+        min_version: '6.0'
 
     deprecated_directive_major_version:
         major_version: 5
@@ -71,4 +71,4 @@ whitelist:
     lines:
         - '.. code-block:: twig'
         - '// bin/console'
-        - '.. code-block:: php'
+        - '.. code-block:: php'

.github/workflows/continuous-integration.yml

@@ -19,55 +19,81 @@ env:
 jobs:
   phpunit:
     name: "PHPUnit"
-    runs-on: "ubuntu-20.04"
+    runs-on: "ubuntu-22.04"
 
     strategy:
+      fail-fast: false
       matrix:
         include:
           - php-version: 7.2
             composer-flags: "--prefer-lowest"
+            doctrine-annotations: true
           - php-version: 7.3
-            symfony-require: "4.4.*"
+            symfony-require: "5.4.*"
+            doctrine-annotations: true
           - php-version: 7.4
-            symfony-require: "5.3.*"
+            symfony-require: "5.4.*"
+            doctrine-annotations: true
           - php-version: 8.0
             symfony-require: "5.4.*"
+            doctrine-annotations: true
           - php-version: 8.1
             symfony-require: "5.4.*"
+            doctrine-annotations: true
+          - php-version: 8.3
+            symfony-require: "5.4.*"
+            doctrine-annotations: true
           - php-version: 8.1
-            symfony-require: "6.0.*"
+            symfony-require: "6.3.*"
+            doctrine-annotations: true
+          - php-version: 8.3
+            symfony-require: "6.3.*"
+            doctrine-annotations: true
+          - php-version: 8.2
+            symfony-require: "7.0.*"
+            doctrine-annotations: false
+          - php-version: 8.3
+            symfony-require: "7.0.*"
+            doctrine-annotations: false
 
     steps:
       - name: "Checkout"
-        uses: "actions/checkout@v2"
+        uses: actions/checkout@v4
         with:
           fetch-depth: 2
 
       - name: "Install PHP without coverage"
-        uses: "shivammathur/setup-php@v2"
+        uses: shivammathur/setup-php@v2
         with:
           php-version: "${{ matrix.php-version }}"
-          tools: composer
+          tools: composer, flex
           coverage: pcov
 
-      - name: Get composer cache directory
+      - name: "Get composer cache directory"
         id: composercache
-        run: echo "::set-output name=dir::$(composer config cache-files-dir)"
+        run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
 
-      - name: Cache dependencies
-        uses: actions/cache@v2
+      - name: "Cache dependencies"
+        uses: actions/cache@v3
         with:
           path: ${{ steps.composercache.outputs.dir }}
           key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.json') }}
           restore-keys: ${{ runner.os }}-composer-
 
+      - name: Install doctrine/annotations
+        if: matrix.doctrine-annotations == true
+        run: |
+          composer require doctrine/annotations --no-update
+
+      - name: Remove packages not compatible symfony 7
+        if: matrix.symfony-require == '7.0.*'
+        run: |
+          composer remove friendsofsymfony/rest-bundle sensio/framework-extra-bundle --no-update --dev
+
       - name: "Install dependencies with composer"
         env:
           SYMFONY_REQUIRE: "${{ matrix.symfony-require }}"
-        run: |
-          composer global config --no-plugins allow-plugins.symfony/flex true
-          composer global require --no-progress --no-scripts --no-plugins symfony/flex
-          composer update --no-interaction --no-progress ${{ matrix.composer-flags }}
+        run: composer update --no-interaction --no-progress ${{ matrix.composer-flags }}
 
-      - name: PHPUnit Tests
-        run: vendor/bin/simple-phpunit --configuration phpunit.xml.dist --coverage-text
+      - name: "PHPUnit Tests"
+        run: vendor/bin/phpunit --configuration phpunit.xml.dist --coverage-text

.github/workflows/docs.yml

@@ -12,17 +12,17 @@ jobs:
 
         steps:
             -   name: "Checkout"
-                uses: actions/checkout@v2
+                uses: actions/checkout@v4
 
             -   name: "Create cache dir"
                 run: mkdir .cache
 
             -   name: "Extract base branch name"
-                run: echo "##[set-output name=branch;]$(echo ${GITHUB_BASE_REF:=${GITHUB_REF##*/}})"
+                run: echo "branch=$(echo ${GITHUB_BASE_REF:=${GITHUB_REF##*/}})" >> $GITHUB_OUTPUT
                 id: extract_base_branch
 
             -   name: "Cache DOCtor-RST"
-                uses: actions/cache@v2
+                uses: actions/cache@v3
                 with:
                     path: .cache
                     key: ${{ runner.os }}-doctor-rst-${{ steps.extract_base_branch.outputs.branch }}

Annotation/Model.php

@@ -50,20 +50,28 @@ final class Model extends Attachable
     public $options;
 
     /**
-     * @param mixed[]  $properties
-     * @param string[] $groups
-     * @param mixed[]  $options
+     * @var array<string, mixed>
+     */
+    public $serializationContext;
+
+    /**
+     * @param mixed[]              $properties
+     * @param string[]             $groups
+     * @param mixed[]              $options
+     * @param array<string, mixed> $serializationContext
      */
     public function __construct(
         array $properties = [],
         string $type = Generator::UNDEFINED,
         array $groups = null,
-        array $options = null
+        array $options = null,
+        array $serializationContext = []
     ) {
         parent::__construct($properties + [
             'type' => $type,
             'groups' => $groups,
             'options' => $options,
+            'serializationContext' => $serializationContext,
         ]);
     }
 }

ApiDocGenerator.php

@@ -20,6 +20,7 @@
 use OpenApi\Analysis;
 use OpenApi\Annotations\OpenApi;
 use OpenApi\Generator;
+use OpenApi\Processors\ProcessorInterface;
 use Psr\Cache\CacheItemPoolInterface;
 use Psr\Log\LoggerAwareTrait;
 
@@ -47,17 +48,25 @@ final class ApiDocGenerator
 
     /** @var string[] */
     private $mediaTypes = ['json'];
+    /**
+     * @var ?string
+     */
+    private $openApiVersion = null;
+
+    /** @var Generator */
+    private $generator;
 
     /**
      * @param DescriberInterface[]|iterable      $describers
      * @param ModelDescriberInterface[]|iterable $modelDescribers
      */
-    public function __construct($describers, $modelDescribers, CacheItemPoolInterface $cacheItemPool = null, string $cacheItemId = null)
+    public function __construct($describers, $modelDescribers, CacheItemPoolInterface $cacheItemPool = null, string $cacheItemId = null, Generator $generator = null)
     {
         $this->describers = $describers;
         $this->modelDescribers = $modelDescribers;
         $this->cacheItemPool = $cacheItemPool;
         $this->cacheItemId = $cacheItemId;
+        $this->generator = $generator ?? new Generator($this->logger);
     }
 
     public function setAlternativeNames(array $alternativeNames)
@@ -70,6 +79,11 @@ public function setMediaTypes(array $mediaTypes)
         $this->mediaTypes = $mediaTypes;
     }
 
+    public function setOpenApiVersion(?string $openApiVersion)
+    {
+        $this->openApiVersion = $openApiVersion;
+    }
+
     public function generate(): OpenApi
     {
         if (null !== $this->openApi) {
@@ -83,15 +97,13 @@ public function generate(): OpenApi
             }
         }
 
-        $generator = new Generator();
-        // Remove OperationId processor as we use a lot of generated annotations which do not have enough information in their context
-        // to generate these ids properly.
-        // @see https://github.com/zircote/swagger-php/issues/1153
-        $generator->setProcessors(array_filter($generator->getProcessors(), function ($processor) {
-            return !$processor instanceof \OpenApi\Processors\OperationId;
-        }));
+        if ($this->openApiVersion) {
+            $this->generator->setVersion($this->openApiVersion);
+        }
 
-        $context = Util::createContext(['version' => $generator->getVersion()]);
+        $this->generator->setProcessors($this->getProcessors($this->generator));
+
+        $context = Util::createContext(['version' => $this->generator->getVersion()]);
 
         $this->openApi = new OpenApi(['_context' => $context]);
         $modelRegistry = new ModelRegistry($this->modelDescribers, $this->openApi, $this->alternativeNames);
@@ -116,7 +128,7 @@ public function generate(): OpenApi
         // Calculate the associated schemas
         $modelRegistry->registerSchemas();
 
-        $analysis->process($generator->getProcessors());
+        $analysis->process($this->generator->getProcessors());
         $analysis->validate();
 
         if (isset($item)) {
@@ -125,4 +137,28 @@ public function generate(): OpenApi
 
         return $this->openApi;
     }
+
+    /**
+     * Get an array of processors that will be used to process the OpenApi object.
+     *
+     * @param Generator $generator The generator instance to get the standard processors from
+     *
+     * @return array<ProcessorInterface|callable> The array of processors
+     */
+    private function getProcessors(Generator $generator): array
+    {
+        // Get the standard processors from the generator.
+        $processors = $generator->getProcessors();
+
+        // Remove OperationId processor as we use a lot of generated annotations which do not have enough information in their context
+        // to generate these ids properly.
+        // @see \Nelmio\ApiDocBundle\OpenApiPhp\Util::createContext
+        foreach ($processors as $key => $processor) {
+            if ($processor instanceof \OpenApi\Processors\OperationId) {
+                unset($processors[$key]);
+            }
+        }
+
+        return $processors;
+    }
 }

CONTRIBUTING.md

@@ -11,7 +11,7 @@ You MUST follow the [PSR-1](http://www.php-fig.org/psr/psr-1/) and
 should really read the recommendations. Can't wait? Use the [PHP-CS-Fixer
 tool](http://cs.sensiolabs.org/).
 
-You MUST run the test suite (run `composer update`, and then execute `vendor/bin/simple-phpunit`).
+You MUST run the test suite (run `composer update`, and then execute `composer run phpunit`).
 
 You MUST write (or update) unit tests.
 

Command/DumpCommand.php

@@ -43,7 +43,7 @@ public function __construct(RenderOpenApi $renderOpenApi)
     /**
      * Configures the dump command.
      */
-    protected function configure()
+    protected function configure(): void
     {
         $availableFormats = $this->renderOpenApi->getAvailableFormats();
         $this
@@ -62,10 +62,7 @@ protected function configure()
         ;
     }
 
-    /**
-     * @return int|void
-     */
-    protected function execute(InputInterface $input, OutputInterface $output)
+    protected function execute(InputInterface $input, OutputInterface $output): int
     {
         $area = $input->getOption('area');
         $format = $input->getOption('format');

DependencyInjection/Compiler/ConfigurationPass.php

@@ -14,6 +14,7 @@
 use Nelmio\ApiDocBundle\ModelDescriber\FormModelDescriber;
 use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
 use Symfony\Component\DependencyInjection\ContainerBuilder;
+use Symfony\Component\DependencyInjection\ContainerInterface;
 use Symfony\Component\DependencyInjection\Reference;
 
 /**
@@ -23,15 +24,16 @@
  */
 final class ConfigurationPass implements CompilerPassInterface
 {
-    public function process(ContainerBuilder $container)
+    public function process(ContainerBuilder $container): void
     {
         if ($container->hasDefinition('form.factory')) {
             $container->register('nelmio_api_doc.model_describers.form', FormModelDescriber::class)
                 ->setPublic(false)
                 ->addArgument(new Reference('form.factory'))
-                ->addArgument(new Reference('annotations.reader'))
+                ->addArgument(new Reference('annotations.reader', ContainerInterface::NULL_ON_INVALID_REFERENCE))
                 ->addArgument($container->getParameter('nelmio_api_doc.media_types'))
                 ->addArgument($container->getParameter('nelmio_api_doc.use_validation_groups'))
+                ->addArgument($container->getParameter('form.type_extension.csrf.enabled'))
                 ->addTag('nelmio_api_doc.model_describer', ['priority' => 100]);
         }
 

DependencyInjection/Compiler/CustomProcessorPass.php

@@ -0,0 +1,59 @@
+<?php
+
+/*
+ * This file is part of the NelmioApiDocBundle package.
+ *
+ * (c) Nelmio
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Nelmio\ApiDocBundle\DependencyInjection\Compiler;
+
+use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
+use Symfony\Component\DependencyInjection\Compiler\PriorityTaggedServiceTrait;
+use Symfony\Component\DependencyInjection\ContainerBuilder;
+use Symfony\Component\DependencyInjection\Reference;
+
+/**
+ * Compiler Pass to identify and register custom processors.
+ *  *
+ * @internal
+ */
+final class CustomProcessorPass implements CompilerPassInterface
+{
+    use PriorityTaggedServiceTrait;
+
+    /**
+     * Process services tagged as 'swagger.processor'.
+     *
+     * @param ContainerBuilder $container The container builder
+     */
+    public function process(ContainerBuilder $container): void
+    {
+        // Find the OpenAPI generator service.
+        $definition = $container->findDefinition('nelmio_api_doc.open_api.generator');
+
+        foreach ($this->findAndSortTaggedServices('nelmio_api_doc.swagger.processor', $container) as $reference) {
+            $id = (string) $reference;
+            $tags = $container->findDefinition($id)->getTags();
+
+            /**
+             * Before which processor should this processor be run?
+             *
+             * @var string|null
+             */
+            $before = null;
+
+            // See if the processor has a 'before' attribute.
+            foreach ($tags as $tag) {
+                if (isset($tag['before'])) {
+                    $before = $tag['before'];
+                }
+            }
+
+            $definition->addMethodCall('addProcessor', [new Reference($id), $before]);
+        }
+    }
+}