Merge branch 'nelmio:master' into property-attr-drop-required

.github/FUNDING.yml

@@ -0,0 +1 @@
+github: DjordyKoert

.github/ISSUE_TEMPLATE/1_Bug_report.yaml

@@ -19,6 +19,23 @@ body:
       description: A clear and concise description of the problem
     validations:
       required: true
+  - type: textarea
+    id: json
+    attributes:
+      label: JSON OpenApi
+      description: Your generated JSON OpenApi documentation (`bin/console nelmio:apidoc:dump`)
+      value: |
+        <details><summary>JSON OpenApi</summary>
+    
+        ```json
+
+        Replace this text with your JSON (`bin/console nelmio:apidoc:dump`)
+
+        ```
+        
+        </details>
+    validations:
+      required: false
   - type: textarea
     id: additional-context
     attributes:

.github/workflows/continuous-integration.yml

@@ -41,18 +41,23 @@ jobs:
             symfony-require: "5.4.*"
             doctrine-annotations: true
           - php-version: 8.1
-            symfony-require: "6.3.*"
+            symfony-require: "6.4.*"
             doctrine-annotations: true
           - php-version: 8.3
-            symfony-require: "6.3.*"
+            symfony-require: "6.4.*"
             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
-
+          - php-version: 8.2
+            symfony-require: "7.1.*"
+            doctrine-annotations: false
+          - php-version: 8.3
+            symfony-require: "7.1.*"
+            doctrine-annotations: false
     steps:
       - name: Checkout
         uses: actions/checkout@v4

.github/workflows/pr-lint.yml

@@ -0,0 +1,22 @@
+name: GitHub PR Lint
+
+on:
+  pull_request_target:
+    types:
+      - opened
+      - edited
+      - reopened
+      - synchronize
+
+jobs:
+  semantic-pr:
+    name: Validate semantic PR title
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Semantic PR title
+        uses: amannn/action-semantic-pull-request@v5
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          subjectPattern: ^(?![A-Z]).+$ # This pattern ensures the subject doesn't start with an uppercase character.

CONTRIBUTING.md

@@ -44,7 +44,14 @@ You SHOULD write (or update) documentation.
 You SHOULD write
 [commit messages that make sense](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
 
-You MUST [rebase your branch](https://git-scm.com/book/en/v2/Git-Branching-Rebasing) before submitting your Pull Request.
+### Pull requests
 
-While creating your Pull Request on GitHub, you MUST write a description which gives the context and/or explains why you
-are creating it.
+You MUST [rebase your branch](https://git-scm.com/book/en/v2/Git-Branching-Rebasing) before submitting your pull request.
+
+You MUST use a pull request title compliant with the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification.
+
+You MUST write a meaningful description which gives the context and/or explains why you
+are creating the pull request.
+
+You SHOULD resolve review comments instead of commenting.
+<sub>Once you've done the work, resolve the conversation by selecting the Resolve conversation button in the PR overview. Avoid posting comments like "I've done the work", or "Done".</sub>

composer.json

@@ -18,16 +18,16 @@
         "psr/cache": "^1.0 || ^2.0 || ^3.0",
         "psr/container": "^1.0 || ^2.0",
         "psr/log": "^1.0 || ^2.0 || ^3.0",
-        "symfony/config": "^5.4 || ^6.0 || ^7.0",
-        "symfony/console": "^5.4 || ^6.0 || ^7.0",
-        "symfony/dependency-injection": "^5.4 || ^6.0 || ^7.0",
+        "symfony/config": "^5.4 || ^6.4 || ^7.0",
+        "symfony/console": "^5.4 || ^6.4 || ^7.0",
+        "symfony/dependency-injection": "^5.4 || ^6.4 || ^7.0",
         "symfony/deprecation-contracts": "^2.1 || ^3",
-        "symfony/framework-bundle": "^5.4.24 || ^6.0 || ^7.0",
-        "symfony/http-foundation": "^5.4 || ^6.0 || ^7.0",
-        "symfony/http-kernel": "^5.4 || ^6.0 || ^7.0",
-        "symfony/options-resolver": "^5.4 || ^6.0 || ^7.0",
-        "symfony/property-info": "^5.4.10 || ^6.0 || ^7.0",
-        "symfony/routing": "^5.4 || ^6.0 || ^7.0",
+        "symfony/framework-bundle": "^5.4.24 || ^6.4 || ^7.0",
+        "symfony/http-foundation": "^5.4 || ^6.4 || ^7.0",
+        "symfony/http-kernel": "^5.4 || ^6.4 || ^7.0",
+        "symfony/options-resolver": "^5.4 || ^6.4 || ^7.0",
+        "symfony/property-info": "^5.4.10 || ^6.4 || ^7.0",
+        "symfony/routing": "^5.4 || ^6.4 || ^7.0",
         "zircote/swagger-php": "^4.6.1"
     },
     "require-dev": {
@@ -43,20 +43,21 @@
         "phpstan/phpstan-strict-rules": "^1.5",
         "phpstan/phpstan-symfony": "^1.3",
         "phpunit/phpunit": "^9.6 || ^10.5",
-        "symfony/asset": "^5.4 || ^6.0 || ^7.0",
-        "symfony/browser-kit": "^5.4 || ^6.0 || ^7.0",
-        "symfony/cache": "^5.4 || ^6.0 || ^7.0",
-        "symfony/dom-crawler": "^5.4 || ^6.0 || ^7.0",
-        "symfony/expression-language": "^5.4 || ^6.0 || ^7.0",
-        "symfony/form": "^5.4 || ^6.0 || ^7.0",
+        "symfony/asset": "^5.4 || ^6.4 || ^7.0",
+        "symfony/browser-kit": "^5.4 || ^6.4 || ^7.0",
+        "symfony/cache": "^5.4 || ^6.4 || ^7.0",
+        "symfony/dom-crawler": "^5.4 || ^6.4 || ^7.0",
+        "symfony/expression-language": "^5.4 || ^6.4 || ^7.0",
+        "symfony/form": "^5.4 || ^6.4 || ^7.0",
         "symfony/phpunit-bridge": "^6.4",
-        "symfony/property-access": "^5.4 || ^6.0 || ^7.0",
-        "symfony/security-csrf": "^5.4 || ^6.0 || ^7.0",
-        "symfony/serializer": "^5.4 || ^6.0 || ^7.0",
-        "symfony/stopwatch": "^5.4 || ^6.0 || ^7.0",
-        "symfony/templating": "^5.4 || ^6.0 || ^7.0",
-        "symfony/twig-bundle": "^5.4 || ^6.0 || ^7.0",
-        "symfony/validator": "^5.4 || ^6.0 || ^7.0",
+        "symfony/property-access": "^5.4 || ^6.4 || ^7.0",
+        "symfony/security-csrf": "^5.4 || ^6.4 || ^7.0",
+        "symfony/serializer": "^5.4 || ^6.4 || ^7.0",
+        "symfony/stopwatch": "^5.4 || ^6.4 || ^7.0",
+        "symfony/templating": "^5.4 || ^6.4 || ^7.0",
+        "symfony/twig-bundle": "^5.4 || ^6.4 || ^7.0",
+        "symfony/uid": "^5.4 || ^6.4 || ^7.0",
+        "symfony/validator": "^5.4 || ^6.4 || ^7.0",
         "willdurand/hateoas-bundle": "^1.0 || ^2.0"
     },
     "conflict": {

config/services.xml

@@ -151,6 +151,10 @@
             <tag name="nelmio_api_doc.object_model.property_describer" priority="-1000" />
         </service>
 
+        <service id="nelmio_api_doc.object_model.property_describers.uuid" class="Nelmio\ApiDocBundle\PropertyDescriber\UuidPropertyDescriber" public="false">
+            <tag name="nelmio_api_doc.object_model.property_describer" />
+        </service>
+
         <!-- Form Type Extensions -->
 
         <service id="nelmio_api_doc.form.documentation_extension" class="Nelmio\ApiDocBundle\Form\Extension\DocumentationExtension">

docs/customization.rst

@@ -68,4 +68,24 @@ Just create a file ``templates/bundles/NelmioApiDocBundle/SwaggerUi/index.html.t
         <script type="text/javascript" src="{{ asset('js/custom-request-signer.js') }}"></script>
     {% endblock javascripts %}
 
-You can have a look at the `original template <https://github.com/nelmio/NelmioApiDocBundle/blob/master/Resources/views/SwaggerUi/index.html.twig>`_, in ``/Resources/views/SwaggerUi/index.html.twig``, to see which blocks can be overridden.
+You can have a look at the `original template <https://github.com/nelmio/NelmioApiDocBundle/blob/master/templates/SwaggerUi/index.html.twig>`_, in ``/templates/SwaggerUi/index.html.twig``, to see which blocks can be overridden.
+
+Assets Loading Options
+-----------------------
+
+The `html_config` settings allow you to configure how assets are loaded for the UI. The `assets_mode` option supports three values: `cdn`, `bundle`, and `offline`.
+
+
+   .. code-block:: yaml
+
+       nelmio_api_doc:
+           html_config:
+               assets_mode: 'cdn' # Other values: 'bundle', 'offline'
+
+`assets_mode`
+~~~~~~~~~~~~~
+
+The three values possible values can be found in `AssetsMode.php <https://github.com/nelmio/NelmioApiDocBundle/blob/master/src/Render/Html/AssetsMode.php>`_
+- **cdn**: Loads assets from `jsDelivr <https://www.jsdelivr.com/>`_.
+- **bundle**: Fetches assets from the bundle in the vendor directory, including updates.
+- **offline**: Loads assets from the local `assets` directory, requiring the developer to update them manually.

src/ApiDocGenerator.php

@@ -20,7 +20,6 @@
 use OpenApi\Analysis;
 use OpenApi\Annotations\OpenApi;
 use OpenApi\Generator;
-use OpenApi\Processors\ProcessorInterface;
 use Psr\Cache\CacheItemPoolInterface;
 use Psr\Log\LoggerAwareTrait;
 
@@ -37,11 +36,9 @@ final class ApiDocGenerator
     /** @var iterable|ModelDescriberInterface[] */
     private $modelDescribers;
 
-    /** @var CacheItemPoolInterface|null */
-    private $cacheItemPool;
+    private ?CacheItemPoolInterface $cacheItemPool;
 
-    /** @var string */
-    private $cacheItemId;
+    private string $cacheItemId;
 
     /** @var string[] */
     private $alternativeNames = [];
@@ -53,8 +50,7 @@ final class ApiDocGenerator
      */
     private $openApiVersion;
 
-    /** @var Generator */
-    private $generator;
+    private Generator $generator;
 
     /**
      * @param DescriberInterface[]|iterable      $describers
@@ -149,7 +145,7 @@ public function generate(): OpenApi
      *
      * @param Generator $generator The generator instance to get the standard processors from
      *
-     * @return array<ProcessorInterface|callable> The array of processors
+     * @return array<callable> The array of processors
      */
     private function getProcessors(Generator $generator): array
     {

src/Controller/SwaggerUiController.php

@@ -12,7 +12,6 @@
 namespace Nelmio\ApiDocBundle\Controller;
 
 use Nelmio\ApiDocBundle\Exception\RenderInvalidArgumentException;
-use Nelmio\ApiDocBundle\Render\Html\AssetsMode;
 use Nelmio\ApiDocBundle\Render\RenderOpenApi;
 use Symfony\Component\HttpFoundation\Request;
 use Symfony\Component\HttpFoundation\Response;
@@ -35,7 +34,6 @@ public function __invoke(Request $request, string $area = 'default'): Response
         try {
             $response = new Response(
                 $this->renderOpenApi->renderFromRequest($request, RenderOpenApi::HTML, $area, [
-                    'assets_mode' => AssetsMode::BUNDLE,
                     'ui_renderer' => $this->uiRenderer,
                 ]),
                 Response::HTTP_OK,

src/DependencyInjection/Configuration.php

@@ -98,7 +98,7 @@ public function getConfigTreeBuilder(): TreeBuilder
                         ->ifTrue(function ($v) {
                             return 0 === count($v) || isset($v['path_patterns']) || isset($v['host_patterns']) || isset($v['documentation']);
                         })
-                        ->then(function ($v) {
+                        ->then(function ($v): array {
                             return ['default' => $v];
                         })
                     ->end()

src/DependencyInjection/NelmioApiDocExtension.php

@@ -35,14 +35,14 @@
 use Symfony\Component\DependencyInjection\ContainerBuilder;
 use Symfony\Component\DependencyInjection\ContainerInterface;
 use Symfony\Component\DependencyInjection\Definition;
+use Symfony\Component\DependencyInjection\Extension\Extension;
 use Symfony\Component\DependencyInjection\Extension\PrependExtensionInterface;
 use Symfony\Component\DependencyInjection\Loader\XmlFileLoader;
 use Symfony\Component\DependencyInjection\Reference;
 use Symfony\Component\DependencyInjection\ServiceLocator;
 use Symfony\Component\HttpKernel\Attribute\MapQueryParameter;
 use Symfony\Component\HttpKernel\Attribute\MapQueryString;
 use Symfony\Component\HttpKernel\Attribute\MapRequestPayload;
-use Symfony\Component\HttpKernel\DependencyInjection\Extension;
 use Symfony\Component\Routing\RouteCollection;
 
 final class NelmioApiDocExtension extends Extension implements PrependExtensionInterface
@@ -171,6 +171,10 @@ public function load(array $configs, ContainerBuilder $container): void
         $container->registerForAutoconfiguration(ModelDescriberInterface::class)
             ->addTag('nelmio_api_doc.model_describer');
 
+        if (!class_exists(\Symfony\Component\Uid\AbstractUid::class)) {
+            $container->removeDefinition('nelmio_api_doc.object_model.property_describers.uuid');
+        }
+
         // Import services needed for each library
         $loader->load('php_doc.xml');
 

src/Model/ModelRegistry.php

@@ -164,7 +164,7 @@ private function generateModelName(Model $model): string
      */
     private function modelToArray(Model $model): array
     {
-        $getType = function (Type $type) use (&$getType) {
+        $getType = function (Type $type) use (&$getType): array {
             return [
                 'class' => $type->getClassName(),
                 'built_in_type' => $type->getBuiltinType(),

src/ModelDescriber/Annotations/SymfonyConstraintAnnotationReader.php

@@ -27,20 +27,14 @@ class SymfonyConstraintAnnotationReader
 {
     use SetsContextTrait;
 
-    /**
-     * @var Reader|null
-     */
-    private $annotationsReader;
+    private ?Reader $annotationsReader;
 
     /**
      * @var OA\Schema
      */
     private $schema;
 
-    /**
-     * @var bool
-     */
-    private $useValidationGroups;
+    private bool $useValidationGroups;
 
     public function __construct(?Reader $annotationsReader, bool $useValidationGroups = false)
     {
@@ -96,6 +90,7 @@ private function processPropertyAnnotations($reflection, OA\Property $property,
                 $existingRequiredFields[] = $propertyName;
 
                 $this->schema->required = array_values(array_unique($existingRequiredFields));
+                $property->nullable = false;
             } elseif ($annotation instanceof Assert\Length) {
                 if (isset($annotation->min)) {
                     $property->minLength = $annotation->min;

src/ModelDescriber/ObjectModelDescriber.php

@@ -31,20 +31,16 @@ class ObjectModelDescriber implements ModelDescriberInterface, ModelRegistryAwar
     use ModelRegistryAwareTrait;
     use ApplyOpenApiDiscriminatorTrait;
 
-    /** @var PropertyInfoExtractorInterface */
-    private $propertyInfo;
-    /** @var ClassMetadataFactoryInterface|null */
-    private $classMetadataFactory;
-    /** @var Reader|null */
-    private $doctrineReader;
+    private PropertyInfoExtractorInterface $propertyInfo;
+    private ?ClassMetadataFactoryInterface $classMetadataFactory;
+    private ?Reader $doctrineReader;
     /** @var PropertyDescriberInterface|PropertyDescriberInterface[] */
     private $propertyDescriber;
     /** @var string[] */
-    private $mediaTypes;
+    private array $mediaTypes;
     /** @var (NameConverterInterface&AdvancedNameConverterInterface)|null */
-    private $nameConverter;
-    /** @var bool */
-    private $useValidationGroups;
+    private ?NameConverterInterface $nameConverter;
+    private bool $useValidationGroups;
 
     /**
      * @param PropertyDescriberInterface|PropertyDescriberInterface[]      $propertyDescribers

src/OpenApiPhp/Util.php

@@ -273,14 +273,20 @@ public static function searchCollectionItem(array $collection, array $properties
     /**
      * Search for an Annotation within the $collection that has its member $index set to $value.
      *
-     * @param mixed[] $collection
-     * @param mixed   $value      The value to search for
+     * @param OA\AbstractAnnotation[] $collection
+     * @param mixed                   $value      The value to search for
      *
      * @return false|int|string
      */
     public static function searchIndexedCollectionItem(array $collection, string $member, $value)
     {
-        return array_search($value, array_column($collection, $member), true);
+        foreach ($collection as $i => $child) {
+            if ($child->{$member} === $value) {
+                return $i;
+            }
+        }
+
+        return false;
     }
 
     /**

src/Processor/MapQueryStringProcessor.php

@@ -18,7 +18,6 @@
 use OpenApi\Analysis;
 use OpenApi\Annotations as OA;
 use OpenApi\Generator;
-use OpenApi\Processors\ProcessorInterface;
 use Symfony\Component\HttpKernel\ControllerMetadata\ArgumentMetadata;
 
 /**
@@ -27,7 +26,7 @@
  *
  * @see SymfonyMapQueryStringDescriber
  */
-final class MapQueryStringProcessor implements ProcessorInterface
+final class MapQueryStringProcessor
 {
     public function __invoke(Analysis $analysis): void
     {