Api Doc Bundle Laravel Package

Miscellaneous Chores

• deps: bump @stoplight/elements from 9.0.15 to 9.0.16 in /utils (#2702) (ff5783b)
• deps: bump swagger-ui-dist from 5.31.0 to 5.32.0 in /utils (#2703) (3d64d5b)

Bug Fixes

• #[MapRequestPayload] & #[MapUploadedFile] combined on same route (#2689) (4ff48e7)
• Choice(multiple: true) warning with string[] and type_info (#2690) (1c608db)
• Count constraint uses minProperties/maxProperties for maps (#2688) (e8196ef)
• LegacyType deprecation warning in Configuration (#2687) (3c06392)

Bug Fixes

• composer: conflict for symfony/property-info versions (#2685) (d9f7213)

Miscellaneous Chores

• deps: bump @stoplight/elements from 9.0.13 to 9.0.15 in /utils (#2676) (19c2ab5)
• gitattributes: exclude dev configs (#2683) (65dfa87)

Bug Fixes

• config: set type_info default correctly in Symfony 8 (#2670) (3e65701)

Bug Fixes

• swagger-ui: dark mode ui background color (#2665) (0303e94)

Miscellaneous Chores

• phpdocumentor: bump support for reflection-docblock & type-resolver (#2666) (75a543d)

Features

• Add support for static callbacks in Symfony choice constraints (#2659) (4d2f627)

Bug Fixes

• OpenApiPhpDescriber: Set annotation name from context, if empty (#2658) (eedb169)

Miscellaneous Chores

• deps: bump @stoplight/elements from 9.0.12 to 9.0.13 in /utils (#2648) (57d40e3)
• deps: bump swagger-ui-dist from 5.30.2 to 5.30.3 in /utils (#2639) (8c804b9)
• deps: bump swagger-ui-dist from 5.30.3 to 5.31.0 in /utils (#2655) (b7fb331)
• symfony: support 8.0 (#2612) (51d6a51)

Bug Fixes

• SplObjectStorage: SplObjectStorage::detach() is deprecated since 8.5, use method SplObjectStorage::offsetUnset() instead (94f6895)

Miscellaneous Chores

• deps: bump @stoplight/elements from 9.0.11 to 9.0.12 in /utils (#2625) (e54c6c2)

Bug Fixes

• configuration: validate type_info option on Symfony 6 (#2615) (3d96b9a)

Features

• #2502: refactor Model::$type from property-info to type-info Type (ef14213)

Bug Fixes

• trigger_deprecation: incorrect & missing trigger_deprecation in Model class (#2613) (52858e6)

Miscellaneous Chores

• php: bump minimum to php 8.2 (#2611) (95b2057)
• symfony: bumped minimum version for Symfony 7 from ^7.1 to ^7.2 (ef14213)

Bug Fixes

• swagger-php 5.7.0 compatatiblity (#2598) (ca4ca49)

Features

• Implement Ulid type description in ClassDescriber (#2556) (5666ba1)

Bug Fixes

• remove unused TypesTrait (#2588) (438894c)

Miscellaneous Chores

• deps: bump @stoplight/elements from 9.0.8 to 9.0.11 in /utils (#2585) (ac85a09)
• deps: bump swagger-ui-dist from 5.29.5 to 5.30.2 in /utils (#2586) (c37c801)

Bug Fixes

• version number in triggered deprecation (#2577) (b5f440c)

Miscellaneous Chores

• deps: bump redoc from 2.5.1 to 2.5.2 in /utils (#2574) (2b49d55)
• deps: bump swagger-ui-dist from 5.29.4 to 5.29.5 in /utils (#2575) (f9fd650)

Bug Fixes

• config: migrate xml to php config (#2566) (2b12914)
• swagger-php: conflict with broken version 5.5.0 (#2568) (a9bbfa7)

Miscellaneous Chores

• deps: bump swagger-ui-dist from 5.29.3 to 5.29.4 in /utils (#2564) (254a487)
• PHPStan v2 (#2572) (3b0abc6)

Miscellaneous Chores

• deps: bump @stoplight/elements from 9.0.6 to 9.0.8 in /utils (#2559) (ab71920)
• deps: bump redoc from 2.5.0 to 2.5.1 in /utils (#2557) (552e1df)
• deps: bump swagger-ui-dist from 5.29.0 to 5.29.3 in /utils (#2560) (9278d86)

Miscellaneous Chores

• deps: bump swagger-ui-dist from 5.28.1 to 5.29.0 in /utils (#2554) (5ad97ac)

Bug Fixes

• ModelRegistry: ensure first registered alternative name is used (#2553) (2f3b3b7)

Miscellaneous Chores

• deps: bump swagger-ui-dist from 5.28.0 to 5.28.1 in /utils (#2548) (dcde65f)

Features

• Model: Allow customizing the name of generated schemas. (#2542) (6a12188)

Miscellaneous Chores

• deps: bump swagger-ui-dist from 5.27.1 to 5.28.0 in /utils (#2538) (0f86e76)

• Schemas deduplication now compare generated schemas to reduce automatically named schemas (Entity / Entity2 / Entity3 / ...).
• Added support for generic types describing

Added support for Symfony's TranslatableInterface

Fixed a bug where using abstract controllers would ignore various attributes like #[OA\Tag] & #[Security] on child classes

Made it possible to automatically generate security definitions based on the #[IsGranted] attribute.

nelmio_api_doc:
    # ...

    areas:
        default:
            security:
                MyBearerScheme:
                    type: 'http'
                    scheme: 'bearer'

Features

• add support for Scalar UI (#2711) (3c80aa6)

Bug Fixes

• exclude BackedEnum from TranslatablePropertyDescriber (#2692) (2c40b2e), closes #2507
• phpstan: apply phpstan fixes (#2721) (3cbe708)
• prevent nullable from triggering oneOf wrapping in JMSModelDescriber (#2693) (7167809), closes #2565
• use FQCN as deduplication key to prevent model merge across namespaces (#2694) (25e8b98)

Miscellaneous Chores

• deps: bump swagger-ui-dist from 5.32.0 to 5.32.1 in /utils (#2712) (b5d5e1f)
• support zircote/swagger-php ^6.0 (#2717) (3add4a7)
• ui: update scalar & stoplight files (#2719) (94d113b)

Made it possible to configure how operation ids are generated.

nelmio_api_doc:
    operation_id_generation: always_prepend

Possible values: always_prepend, conditionally_prepend, no_prepend or enum instance of Nelmio\ApiDocBundle\Describer\OperationIdGeneration

• Support of attribute MapQueryParameter with a regexp has been improved, it now converts the regexp from PCRE to ECMA-262 for better compliance with OpenApi.

• Added a #[Ignore] attribute that allows a property to be excluded from the generated schema.

<?php

use Nelmio\ApiDocBundle\Attribute\Ignore;

class Foo
{
    #[Ignore]
    private string $ignoredProperty;
}

• Added support for the #[MapUploadedFile] symfony controller argument attribute

• Added Stoplight as an alternative UI option. https://stoplight.io/open-source/elements.

• Passing an array key value with a list of strings to the Areas annotation/attribute is deprecated. Pass the list of strings directly.

-#[Areas(properties: ['value' => ['foo', 'bar']])]
+#[Areas(properties: ['foo', 'bar'])]

-#[Areas(['value' => ['foo', 'bar']])]
+#[Areas(['foo', 'bar'])]

• Configuration option with_annotation has been deprecated in favor of with_attribute

nelmio_api_doc:
    areas:
        path_patterns:
            - ^/api/foo
-       with_annotation: true
+       with_attribute: true

• Added support for the symfony/type-info component

nelmio_api_doc:
  type_info: true

• Changed minimum Symfony version for 7.x from 7.0 to 7.1

• Fixed Symfony 7.2 deprecation of tagged arguments

• Added new optional parameter $context to PropertyDescriberInterface::supports()

• Deprecated null type from $options in Nelmio\ApiDocBundle\Attribute\Model::__construct(). Pass an empty array ([]) instead.
• Deprecated null type from $options in NNelmio\ApiDocBundle\Attribute\Model::__construct(). Pass an empty array ([]) instead.

• Bumped swagger-ui files from 5.18.1 to 5.18.2
• Bumped redoc files to 2.2.0

• Fixed incorrect directory updated for swagger-ui files from version 4.33.2

• Bumped swagger-ui files to 5.18.1
• Fixed explicitly set default values defined in #[OA\Property] being overwritten

• Fixed custom JMS enum type handling
• Added support for name based serialisation of JMS enums

• Deprecated Nelmio\ApiDocBundle\Annotation namespace in favor of Nelmio\ApiDocBundle\Attribute namespace in preparation for 5.x. Consider upgrading to the new attribute syntax.

- use Nelmio\ApiDocBundle\Annotation\Areas;
- use Nelmio\ApiDocBundle\Annotation\Model;
- use Nelmio\ApiDocBundle\Annotation\Operation;
- use Nelmio\ApiDocBundle\Annotation\Security;

+ use Nelmio\ApiDocBundle\Attribute\Areas;
+ use Nelmio\ApiDocBundle\Attribute\Model;
+ use Nelmio\ApiDocBundle\Attribute\Operation;
+ use Nelmio\ApiDocBundle\Attribute\Security;

• Added support to configure options and serializationContext via nelmio_api_doc.models.names.
• Fixed serializationContext not being applied to nested models.

• Added support to opt out of JMS serializer usage per endpoint by setting useJms in the serializationContext.

  #[OA\Response(response: 200, content: new Model(type: UserDto::class, serializationContext: ["useJms" => false]))]
  

• Create top level OpenApi Tag from Tags top level annotations/attributes

• Add ability to configure UI through configuration

nelmio_api_doc:
  html_config:
    assets_mode: bundle
    redocly_config:
      expandResponses: '200,201'
      hideDownloadButton: true
    swagger_ui_config:
      deepLinking: true

• Calling DocumentationExtension::getExtendedType() has been deprecated in favor of DocumentationExtension::getExtendedTypes() to align with the deprecation introduced with symfony/symfony version 4.2.

• Added support for [JMS @Discriminator](https://jmsyst.com/libs/serializer/master/reference/annotations#discriminator) annotation/attribute

  #[\JMS\Serializer\Annotation\Discriminator(field: 'type', map: ['car' => Car::class, 'plane' => Plane::class])]
  abstract class Vehicle { }
  class Car extends Vehicle { }
  class Plane extends Vehicle { }
  

• Added support for some integer ranges (https://phpstan.org/writing-php-code/phpdoc-types#integer-ranges).
  Annotations attached to integer properties like:

    /**
     * [@var](https://github.com/var) int<6, 11>
     * [@var](https://github.com/var) int<min, 11>
     * [@var](https://github.com/var) int<6, max>
     * [@var](https://github.com/var) positive-int
     * [@var](https://github.com/var) negative-int
     */
  

  will be interpreted as appropriate minimum and maximum properties in the generated OpenAPI specification.

Minor breaking change

Dropped support for PHP 7.2 and PHP 7.3. PHP 7.4 is the minimum required version now.

• Cache configuration option nelmio_api_doc.cache.item_id now automatically gets the area appended.

  nelmio_api_doc:
      cache:
          pool: app.cache
          item_id: nelmio_api_doc.docs
      areas:
          default: 
              ...
          area1:   
              ...
  

  Result in cache keys: nelmio_api_doc.docs.default & nelmio_api_doc.docs.area1 to be used respectively.
• Added cache configuration option per area.

  nelmio_api_doc:
      areas:
          default: # Manual cache configuration
              cache:
                  pool: app.cache
                  item_id: nelmio_api_doc.docs.default
              ...
          area1:   
              cache:
                  pool: app.cache
                  item_id: nelmio_api_doc.docs.area1
              ...
  

  Non-configured options will be inherited from nelmio_api_doc.cache.
• Fixed vendor extensions (x-*) from configuration not being outputted in the generated specification.

  nelmio_api_doc:
      documentation:
          info:
              title: 'My API'
              description: 'My API description'
              x-foo: 'bar'
  

  Now results in JSON specification:

  {
    ...
    "info": {
      "title": "API",
      "version": "1.0",
      "x-foo": "bar"
    },
    ...
  }
  

• Updated nullable enum handling to align with the behaviour of other object types. It now uses wraps nullable enums with oneOf instead of allOf.

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

    bin/console assets:install
  

Breaking change

If your codebase mentions a file or directory by path then an update to this path is necessary. For example to following configuration:

doc-api:
    resource: "[@NelmioApiDocBundle](https://github.com/NelmioApiDocBundle)/Resources/config/routing/swaggerui.xml"
    prefix: /api/doc

Becomes:

doc-api:
    resource: "[@NelmioApiDocBundle](https://github.com/NelmioApiDocBundle)/config/routing/swaggerui.xml"
    prefix: /api/doc

• Added bundle configuration options nelmio_api_doc.cache.pool and nelmio_api_doc.cache.item_id.

  nelmio_api_doc:
      cache:
          pool: app.cache
          item_id: nelmio_api_doc.docs
  

• Added Redocly as an alternative to Swagger UI. https://github.com/Redocly/redoc.
• Added support for describing dictionary types in OpenAPI 3.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.

• Added support of OpenAPI 3.0. The internals were completely reworked and this version introduces BC breaks.

• Added [@SerializedName](https://github.com/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](https://github.com/SWG) annotations support at methods level in models

• 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. You can re-add Google Fonts again manually by overriding the template.

• The Twig template for the Swagger UI now contains blocks to make it easier to overwrite certain parts. See the official documentation how to do this.

• Add a documentation form extension. Use the documentation option to define how a form field is documented.

• Allow references to config definitions in controllers.

• Using [@Model](https://github.com/Model) implicitly in [@SWG](https://github.com/SWG)\Schema, [@SWG](https://github.com/SWG)\Items and [@SWG](https://github.com/SWG)\Property is deprecated. Use ref=[@Model](https://github.com/Model)() instead.

  Before:

  /**
   * This was considered as an array of models.
   *
   * [@SWG](https://github.com/SWG)\Property([@Model](https://github.com/Model)(type=FooClass::class))
   */
  

  After:

  /**
   * For an individual object:
   * [@SWG](https://github.com/SWG)\Property(ref=[@Model](https://github.com/Model)(type=FooClass::class))
   *
   * For an array:
   * [@SWG](https://github.com/SWG)\Property(type="array", [@SWG](https://github.com/SWG)\Items(ref=[@Model](https://github.com/Model)(type=FooClass::class)))
   */
  

Config

• nelmio_api_doc.areas added support to filter by host patterns.

  nelmio_api_doc:
      areas: [ host_patterns: [ ^api\. ] ]
  

• Added dependency for "symfony/options-resolver:^3.4.4|^4.0"

• Added Symfony Validator constraints support

Symfony Forms

• Support for boolean checkbox
• Support for integer

JMS Serializer

• Support JMS int (alias for integer)
• Also process phpdoc annotations

SwaggerPHP

• Handle enum and default properties from SwaggerPHP annotation
• Support [@Security](https://github.com/Security) annotations

Config

• nelmio_api_doc.routes has been replaced by nelmio_api_doc.areas. Please update your config accordingly.

  Before:

  nelmio_api_doc:
      routes: [ path_patterns: [ /api ] ]
  

  After:

  nelmio_api_doc:
      areas: [ path_patterns: [ /api ] ]
  

Large refactoring introducing zircote/swagger-php for swagger annotations.

See UPGRADE-3.0.md for upgrading instructions.