Merge branch 'master' into conventional-commits

nelmio · Jun 12, 2024 · 18a7112 · 18a7112
2 parents 24083cf + c21aead
commit 18a7112
Show file tree

Hide file tree

Showing 38 changed files with 692 additions and 94 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1,20 @@
 CHANGELOG
 =========
 
+4.26.0
+-----
+* Add ability to configure UI through configuration
+```yaml
+nelmio_api_doc:
+  html_config:
+    assets_mode: bundle
+    redocly_config:
+      expandResponses: '200,201'
+      hideDownloadButton: true
+    swagger_ui_config:
+      deepLinking: true
+```
+
 4.25.0
 -----
 * Added support for [JMS @Discriminator](https://jmsyst.com/libs/serializer/master/reference/annotations#discriminator) annotation/attribute

diff --git a/config/services.xml b/config/services.xml
@@ -40,6 +40,7 @@
         </service>
         <service id="nelmio_api_doc.render_docs.html" class="Nelmio\ApiDocBundle\Render\Html\HtmlOpenApiRenderer" public="false">
             <argument type="service" id="twig" />
+            <argument type="collection" />
         </service>
         <service id="nelmio_api_doc.render_docs.html.asset" class="Nelmio\ApiDocBundle\Render\Html\GetNelmioAsset" public="false">
             <argument type="service" id="twig.extension.assets" />

diff --git a/docs/commands.rst b/docs/commands.rst
@@ -37,9 +37,11 @@ or configure UI configuration, use the ``--html-config`` option.
 - ``server_url`` - API url, useful if static documentation is not hosted on API url
 - ``swagger_ui_config`` - `configure Swagger UI`_
     - ``"supportedSubmitMethods":[]`` disables the sandbox
+- ``redocly_config`` - `configure Redocly`_
 
 .. code-block:: bash
 
     $ php bin/console nelmio:apidoc:dump --format=html --html-config '{"assets_mode":"offline","server_url":"https://example.com","swagger_ui_config":{"supportedSubmitMethods":[]}}' > api.html
 
 .. _`configure Swagger UI`: https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/
+.. _`configure Redocly`: https://redocly.com/docs/redoc/config/
diff --git a/docs/customization.rst b/docs/customization.rst
@@ -25,16 +25,34 @@ Just create a file ``templates/bundles/NelmioApiDocBundle/SwaggerUi/index.html.t
     {% extends '@!NelmioApiDoc/SwaggerUi/index.html.twig' %}
 
     {#
-        Change swagger UI configuration
+        Change Swagger UI configuration
         All parameters are explained on Swagger UI website:
         https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/
     #}
     {% block swagger_initialization %}
         <script type="text/javascript">
-            window.onload = loadSwaggerUI({
-                defaultModelsExpandDepth: -1,
-                deepLinking: true,
-            });
+            window.onload = () => {
+                loadSwaggerUI({
+                    defaultModelsExpandDepth: -1,
+                    deepLinking: true,
+                });
+            };
+        </script>
+    {% endblock %}
+
+    {#
+        Change Redocly configuration
+        All parameters are explained on Redocly website:
+        https://redocly.com/docs/redoc/config/
+    #}
+    {% block swagger_initialization %}
+        <script type="text/javascript">
+            window.onload = () => {
+                loadRedocly({
+                    expandResponses: '200,201',
+                    hideDownloadButton: true,
+                });
+            };
         </script>
     {% endblock %}
 

diff --git a/phpstan-baseline.neon b/phpstan-baseline.neon
@@ -1,15 +1,5 @@
 parameters:
 	ignoreErrors:
-		-
-			message: "#^Property Nelmio\\\\ApiDocBundle\\\\Annotation\\\\Model\\:\\:\\$_required type has no value type specified in iterable type array\\.$#"
-			count: 1
-			path: src/Annotation/Model.php
-
-		-
-			message: "#^Property Nelmio\\\\ApiDocBundle\\\\Annotation\\\\Security\\:\\:\\$_required type has no value type specified in iterable type array\\.$#"
-			count: 1
-			path: src/Annotation/Security.php
-
 		-
 			message: "#^Only booleans are allowed in an if condition, mixed given\\.$#"
 			count: 1

diff --git a/public/init-redocly-ui.js b/public/init-redocly-ui.js
@@ -1,7 +1,7 @@
 'use strict';
 
-window.onload = () => {
+function loadRedocly(userOptions = {}) {
     const data = JSON.parse(document.getElementById('swagger-data').innerText);
 
-    Redoc.init(data.spec, {}, document.getElementById('swagger-ui'));
-};
+    Redoc.init(data.spec, userOptions, document.getElementById('swagger-ui'));
+}
diff --git a/src/ApiDocGenerator.php b/src/ApiDocGenerator.php
@@ -37,11 +37,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 +51,7 @@ final class ApiDocGenerator
      */
     private $openApiVersion;
 
-    /** @var Generator */
-    private $generator;
+    private Generator $generator;
 
     /**
      * @param DescriberInterface[]|iterable      $describers

diff --git a/src/Command/DumpCommand.php b/src/Command/DumpCommand.php
@@ -18,6 +18,9 @@
 use Symfony\Component\Console\Input\InputOption;
 use Symfony\Component\Console\Output\OutputInterface;
 
+/**
+ * @final
+ */
 class DumpCommand extends Command
 {
     private RenderOpenApi $renderOpenApi;
@@ -28,6 +31,7 @@ class DumpCommand extends Command
     private $defaultHtmlConfig = [
         'assets_mode' => AssetsMode::CDN,
         'swagger_ui_config' => [],
+        'redocly_config' => [],
     ];
 
     public function __construct(RenderOpenApi $renderOpenApi)
@@ -67,7 +71,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         $options = [];
         if (RenderOpenApi::HTML === $format) {
             $rawHtmlConfig = json_decode($input->getOption('html-config'), true);
-            $options = is_array($rawHtmlConfig) ? $rawHtmlConfig : $this->defaultHtmlConfig;
+            $options = is_array($rawHtmlConfig) ? $rawHtmlConfig + $this->defaultHtmlConfig : $this->defaultHtmlConfig;
         } elseif (RenderOpenApi::JSON === $format) {
             $options = [
                 'no-pretty' => $input->hasParameterOption(['--no-pretty']),

diff --git a/src/Controller/SwaggerUiController.php b/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,

diff --git a/src/DependencyInjection/Configuration.php b/src/DependencyInjection/Configuration.php
@@ -11,6 +11,7 @@
 
 namespace Nelmio\ApiDocBundle\DependencyInjection;
 
+use Nelmio\ApiDocBundle\Render\Html\AssetsMode;
 use Symfony\Component\Config\Definition\Builder\TreeBuilder;
 use Symfony\Component\Config\Definition\ConfigurationInterface;
 
@@ -55,6 +56,29 @@ public function getConfigTreeBuilder(): TreeBuilder
                     ->defaultValue(['json'])
                     ->prototype('scalar')->end()
                 ->end()
+                ->arrayNode('html_config')
+                    ->info('UI configuration options')
+                    ->addDefaultsIfNotSet()
+                    ->children()
+                        ->scalarNode('assets_mode')
+                            ->defaultValue(AssetsMode::CDN)
+                            ->validate()
+                                ->ifNotInArray([AssetsMode::BUNDLE, AssetsMode::CDN, AssetsMode::OFFLINE])
+                                ->thenInvalid('Invalid assets mode %s')
+                            ->end()
+                        ->end()
+                        ->arrayNode('swagger_ui_config')
+                            ->info('https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/')
+                            ->addDefaultsIfNotSet()
+                            ->ignoreExtraKeys(false)
+                        ->end()
+                        ->arrayNode('redocly_config')
+                            ->info('https://redocly.com/docs/redoc/config/')
+                            ->addDefaultsIfNotSet()
+                            ->ignoreExtraKeys(false)
+                        ->end()
+                    ->end()
+                ->end()
                 ->arrayNode('areas')
                     ->info('Filter the routes that are documented')
                     ->defaultValue(
@@ -74,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()

diff --git a/src/DependencyInjection/NelmioApiDocExtension.php b/src/DependencyInjection/NelmioApiDocExtension.php
@@ -227,6 +227,8 @@ public function load(array $configs, ContainerBuilder $container): void
 
             $container->removeDefinition('nelmio_api_doc.render_docs.html');
             $container->removeDefinition('nelmio_api_doc.render_docs.html.asset');
+        } elseif (isset($config['html_config'])) {
+            $container->getDefinition('nelmio_api_doc.render_docs.html')->replaceArgument(1, $config['html_config']);
         }
 
         // ApiPlatform support

diff --git a/src/Describer/OpenApiPhpDescriber.php b/src/Describer/OpenApiPhpDescriber.php
@@ -90,10 +90,6 @@ public function describe(OA\OpenApi $api): void
 
             $annotations = array_merge($annotations, $this->getAttributesAsAnnotation($method, $context));
 
-            if (0 === count($annotations) && 0 === count($classAnnotations[$declaringClass->getName()])) {
-                continue;
-            }
-
             $implicitAnnotations = [];
             $mergeProperties = new \stdClass();
 
@@ -154,14 +150,14 @@ public function describe(OA\OpenApi $api): void
                 $implicitAnnotations[] = $annotation;
             }
 
-            if ([] === $implicitAnnotations && [] === get_object_vars($mergeProperties)) {
-                continue;
-            }
-
             foreach ($httpMethods as $httpMethod) {
                 $operation = Util::getOperation($path, $httpMethod);
-                $operation->merge($implicitAnnotations);
-                $operation->mergeProperties($mergeProperties);
+                if ([] !== $implicitAnnotations) {
+                    $operation->merge($implicitAnnotations);
+                }
+                if ([] !== get_object_vars($mergeProperties)) {
+                    $operation->mergeProperties($mergeProperties);
+                }
 
                 if (Generator::UNDEFINED === $operation->operationId) {
                     $operation->operationId = $httpMethod.'_'.$routeName;

diff --git a/src/Model/ModelRegistry.php b/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(),

diff --git a/src/ModelDescriber/Annotations/SymfonyConstraintAnnotationReader.php b/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)
     {
@@ -213,7 +207,7 @@ private function getAnnotations(Context $parentContext, $reflection, ?array $val
      */
     private function locateAnnotations($reflection): \Traversable
     {
-        if (\PHP_VERSION_ID >= 80000) {
+        if (\PHP_VERSION_ID >= 80000 && class_exists(Constraint::class)) {
             foreach ($reflection->getAttributes(Constraint::class, \ReflectionAttribute::IS_INSTANCEOF) as $attribute) {
                 yield $attribute->newInstance();
             }

diff --git a/src/ModelDescriber/JMSModelDescriber.php b/src/ModelDescriber/JMSModelDescriber.php
@@ -152,6 +152,7 @@ public function describe(Model $model, OA\Schema $schema)
                 } catch (\ReflectionException $ignored) {
                 }
             }
+            $this->checkRequiredFields($reflections, $schema, $name);
             if (null !== $item->setter) {
                 try {
                     $reflections[] = new \ReflectionMethod($item->class, $item->setter);
@@ -397,4 +398,34 @@ private function propertyTypeUsesGroups(array $type): ?bool
             return null;
         }
     }
+
+    /**
+     * Mark property as required if it is not nullable.
+     *
+     * @param array<\ReflectionProperty|\ReflectionMethod> $reflections
+     */
+    private function checkRequiredFields(array $reflections, OA\Schema $schema, string $name): void
+    {
+        foreach ($reflections as $reflection) {
+            $nullable = false;
+            if ($reflection instanceof \ReflectionProperty) {
+                $type = PHP_VERSION_ID >= 70400 ? $reflection->getType() : null;
+                if (null !== $type && !$type->allowsNull()) {
+                    $nullable = true;
+                }
+            } elseif ($reflection instanceof \ReflectionMethod) {
+                $returnType = $reflection->getReturnType();
+                if (null !== $returnType && !$returnType->allowsNull()) {
+                    $nullable = true;
+                }
+            }
+            if ($nullable) {
+                $required = Generator::UNDEFINED !== $schema->required ? $schema->required : [];
+                $required[] = $name;
+
+                $schema->required = $required;
+                break;
+            }
+        }
+    }
 }
diff --git a/src/ModelDescriber/ObjectModelDescriber.php b/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