Merge branch 'master' into fork/DominicLuidold/trigger-deprecation-calls

# Conflicts:
#	CHANGELOG.md

.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:

.php-cs-fixer.dist.php

@@ -20,5 +20,6 @@
 file that was distributed with this source code.
 HEADER
         ],
+        'trailing_comma_in_multiline' => false,
     ])
     ->setFinder($finder);

CHANGELOG.md

@@ -1,12 +1,27 @@
-CHANGELOG
-=========
+# CHANGELOG
+
+## 4.32.0
+
+* Added support to configure `options` and `serializationContext` via `nelmio_api_doc.models.names`.
+* Fixed `serializationContext` not being applied to nested models.
+
+## 4.31.0
+
+* Added support to opt out of JMS serializer usage per endpoint by setting `useJms` in the serializationContext.
+  ```php
+  #[OA\Response(response: 200, content: new Model(type: UserDto::class, serializationContext: ["useJms" => false]))]
+  ```
+
+## 4.30.0
+* Create top level OpenApi Tag from Tags top level annotations/attributes
+
+## 4.25.3
 
-4.28.1
------
 * Calling `DocumentationExtension::getExtendedType()` has been deprecated in favor of `DocumentationExtension::getExtendedTypes()` to align with the deprecation introduced with `symfony/symfony` version `4.2`.
 
-4.26.0
------
+
+## 4.26.0
+
 * Add ability to configure UI through configuration
 ```yaml
 nelmio_api_doc:
@@ -19,8 +34,8 @@ nelmio_api_doc:
       deepLinking: true
 ```
 
-4.25.0
------
+## 4.25.0
+
 * Added support for [JMS @Discriminator](https://jmsyst.com/libs/serializer/master/reference/annotations#discriminator) annotation/attribute
   ```php
   #[\JMS\Serializer\Annotation\Discriminator(field: 'type', map: ['car' => Car::class, 'plane' => Plane::class])]
@@ -29,8 +44,8 @@ nelmio_api_doc:
   class Plane extends Vehicle { }
   ```
 
-4.24.0
------
+## 4.24.0
+
 * Added support for some integer ranges (https://phpstan.org/writing-php-code/phpdoc-types#integer-ranges).  
   Annotations attached to integer properties like:
   ```php
@@ -47,8 +62,8 @@ nelmio_api_doc:
 ### Minor breaking change
 Dropped support for PHP 7.2 and PHP 7.3. PHP 7.4 is the minimum required version now.
 
-4.23.0
------
+## 4.23.0
+
 * Cache configuration option `nelmio_api_doc.cache.item_id` now automatically gets the area appended.
   ```yml
   nelmio_api_doc:
@@ -101,8 +116,8 @@ Dropped support for PHP 7.2 and PHP 7.3. PHP 7.4 is the minimum required version
   ```
 * Updated nullable enum handling to align with the behaviour of other object types. It now uses wraps nullable enums with `oneOf` instead of `allOf`.
 
-4.22.0
------
+## 4.22.0
+
 * Updated bundle directory structure to recommended file structure as described in https://symfony.com/doc/7.0/bundles/best_practices.html.
 
   It might be necessary to reinstall the assets:
@@ -124,8 +139,8 @@ doc-api:
     prefix: /api/doc
 ```
 
-4.21.0
------
+## 4.21.0
+
 * Added bundle configuration options `nelmio_api_doc.cache.pool` and `nelmio_api_doc.cache.item_id`.
   ```yml
   nelmio_api_doc:
@@ -134,29 +149,30 @@ doc-api:
           item_id: nelmio_api_doc.docs
   ```
 
-4.20.0
------
+## 4.20.0
+
 * Added Redocly as an alternative to Swagger UI. https://github.com/Redocly/redoc.
 * Added support for describing dictionary types in OpenAPI 3.0.
 
-4.17.0
------
+## 4.17.0
+
 * Passing groups to `PropertyDescriberInterface::describe()` via the `$groups` parameter is deprecated, the parameter will get removed in a future version. Pass groups via `$context['groups']` instead.
 
-4.0.0
------
+
+## 4.0.0
+
 * Added support of OpenAPI 3.0. The internals were completely reworked and this version introduces BC breaks.
 
-3.7.0
------
+## 3.7.0
+
 
 * Added `@SerializedName` annotation support and name converters when using Symfony >= 4.2.
 * Removed pattern added from the Expression Violation message.
 * Added FOSRestBundle 3.x support
 * Added `@SWG` annotations support at methods level in models
 
-3.3.0
------
+## 3.3.0
+
 
 * Usage of Google Fonts was removed. System fonts `serif` / `sans` will be used instead.
   This can lead to a different look on different operating systems.
@@ -165,8 +181,7 @@ doc-api:
 * The Twig template for the Swagger UI now contains blocks to make it easier to overwrite certain parts.
   See the [official documentation](https://symfony.com/doc/current/bundles/NelmioApiDocBundle/customization.html) how to do this.
 
-3.2.0 (2018-03-24)
-------------------
+## 3.2.0 (2018-03-24)
 
 * Add a documentation form extension. Use the ``documentation`` option to define how a form field is documented.
 * Allow references to config definitions in controllers.
@@ -202,8 +217,7 @@ Config
 
 * Added dependency for "symfony/options-resolver:^3.4.4|^4.0"
 
-3.1.0 (2018-01-28)
-------------------
+## 3.1.0 (2018-01-28)
 
 * Added Symfony Validator constraints support
 
@@ -234,8 +248,7 @@ Config
       areas: [ path_patterns: [ /api ] ]
   ```
 
-3.0.0 (2017-12-10)
-------------------
+## 3.0.0 (2017-12-10)
 
 Large refactoring introducing `zircote/swagger-php` for swagger annotations.
 

config/services.xml

@@ -139,10 +139,6 @@
             <tag name="nelmio_api_doc.object_model.property_describer" />
         </service>
 
-        <service id="nelmio_api_doc.object_model.property_describers.required" class="Nelmio\ApiDocBundle\PropertyDescriber\RequiredPropertyDescriber" public="false">
-            <tag name="nelmio_api_doc.object_model.property_describer" />
-        </service>
-
         <service id="nelmio_api_doc.object_model.property_describers.object" class="Nelmio\ApiDocBundle\PropertyDescriber\ObjectPropertyDescriber" public="false">
             <tag name="nelmio_api_doc.object_model.property_describer" priority="-1000" />
         </service>

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.

docs/index.rst

@@ -109,7 +109,7 @@ It generates an OpenAPI documentation from your Symfony app thanks to
 routes, etc.
 
 If you configured the ``app.swagger_ui`` route above, you can browse your
-documentation at `http://example.org/api/doc`.
+documentation at ``http://example.org/api/doc``.
 
 Using the bundle
 ----------------
@@ -350,7 +350,7 @@ properties and validator constraints. Take the model class below:
         }
 
 The ``NotBlank`` constraint will apply only to the ``default`` and ``create``
-group, but not ``update``. In more practical terms: the `username` property
+group, but not ``update``. In more practical terms: the ``username`` property
 would show as ``required`` for both model create and default, but not update.
 When using code generators to build API clients, this often translates into
 client side validation and types. ``NotBlank`` adding ``required`` will cause
@@ -509,6 +509,18 @@ General PHP objects
         nelmio_api_doc:
             models: { use_jms: false }
 
+    Alternatively, it is also possible to opt out of JMS serializer usage per endpoint by setting ``useJms`` in the serializationContext:
+
+    .. configuration-block::
+
+        .. code-block:: php-annotations
+
+            /** @OA\Response(response=200, @Model(type=UserDto::class, serializationContext={"useJms"=false})) */
+
+        .. code-block:: php-attributes
+
+            #[OA\Response(response: 200, content: new Model(type: UserDto::class, serializationContext: ["useJms" => false]))]
+
     When using the JMS serializer combined with `willdurand/Hateoas`_ (and the `BazingaHateoasBundle`_),
     HATEOAS metadata are automatically extracted
 

docs/symfony_attributes.rst

@@ -197,4 +197,4 @@ Make sure to use at least php 8.1 (attribute support) to make use of this functi
 .. _`Symfony MapQueryString`: https://symfony.com/doc/current/controller.html#mapping-the-whole-query-string
 .. _`Symfony MapQueryParameter`: https://symfony.com/doc/current/controller.html#mapping-query-parameters-individually
 .. _`Symfony MapRequestPayload`: https://symfony.com/doc/current/controller.html#mapping-request-payload
-.. _`RouteArgumentDescriberInterface`: https://github.com/DjordyKoert/NelmioApiDocBundle/blob/master/RouteDescriber/RouteArgumentDescriber/RouteArgumentDescriberInterface.php
+.. _`RouteArgumentDescriberInterface`: https://github.com/DjordyKoert/NelmioApiDocBundle/blob/master/src/RouteDescriber/RouteArgumentDescriber/RouteArgumentDescriberInterface.php

public/init-swagger-ui.js

@@ -25,26 +25,52 @@ function loadSwaggerUI(userOptions = {}) {
 
   const storageKey = 'nelmio_api_auth';
 
-  // if we have auth in storage use it
-  if (sessionStorage.getItem(storageKey)) {
-    try {
-      ui.authActions.authorize(JSON.parse(sessionStorage.getItem(storageKey)));
-    } catch (ignored) {
-      // catch any errors here so it does not stop script execution
+  function getAuthorizationsFromStorage() {
+    if (sessionStorage.getItem(storageKey)) {
+      try {
+        return JSON.parse(sessionStorage.getItem(storageKey));
+      } catch (ignored) {
+        // catch any errors here so it does not stop script execution
+      }
     }
+
+    return {};
+  }
+
+  // if we have auth in storage use it
+  try {
+    const currentAuthorizations = getAuthorizationsFromStorage();
+    Object.keys(currentAuthorizations).forEach(k => ui.authActions.authorize({[k]: currentAuthorizations[k]}));
+  } catch (ignored) {
+    // catch any errors here so it does not stop script execution
   }
 
   // hook into authorize to store the auth in local storage when user performs authorization
   const currentAuthorize = ui.authActions.authorize;
   ui.authActions.authorize = function (payload) {
-    sessionStorage.setItem(storageKey, JSON.stringify(payload));
+    try {
+      sessionStorage.setItem(storageKey, JSON.stringify(Object.assign(
+        getAuthorizationsFromStorage(),
+        payload
+      )));
+    } catch (ignored) {
+      // catch any errors here so it does not stop script execution
+    }
+
     return currentAuthorize(payload);
   };
 
   // hook into logout to clear auth from storage if user logs out
   const currentLogout = ui.authActions.logout;
   ui.authActions.logout = function (payload) {
-    sessionStorage.removeItem(storageKey);
+    try {
+      let currentAuth = getAuthorizationsFromStorage();
+      payload.forEach(k => delete currentAuth[k]);
+      sessionStorage.setItem(storageKey, JSON.stringify(currentAuth));
+    } catch (ignored) {
+      // catch any errors here so it does not stop script execution
+    }
+
     return currentLogout(payload);
   };
 

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;
 
@@ -146,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/DependencyInjection/Configuration.php

@@ -175,6 +175,17 @@ public function getConfigTreeBuilder(): TreeBuilder
                                             ->thenInvalid('Model groups must be either `null` or an array.')
                                         ->end()
                                     ->end()
+                                    ->variableNode('options')
+                                        ->defaultValue(null)
+                                        ->validate()
+                                            ->ifTrue(function ($v) { return null !== $v && !is_array($v); })
+                                            ->thenInvalid('Model options must be either `null` or an array.')
+                                        ->end()
+                                    ->end()
+                                    ->arrayNode('serializationContext')
+                                        ->defaultValue([])
+                                        ->prototype('variable')->end()
+                                    ->end()
                                     ->arrayNode('areas')
                                         ->defaultValue([])
                                         ->prototype('scalar')->end()