5.10.0 (2026-04-10)
- 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)
- 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)
5.9.5 (2026-03-04)
- 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)
5.9.4 (2026-02-20)
#[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)
5.9.3 (2026-02-04)
- deps: bump @stoplight/elements from 9.0.13 to 9.0.15 in /utils (#2676) (19c2ab5)
- gitattributes: exclude dev configs (#2683) (65dfa87)
5.9.2 (2026-01-08)
5.9.1 (2026-01-08)
5.9.0 (2026-01-02)
5.8.3 (2026-01-02)
- 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)
5.8.2 (2025-11-28)
- SplObjectStorage:
SplObjectStorage::detach()is deprecated since8.5, use methodSplObjectStorage::offsetUnset()instead (94f6895)
5.8.1 (2025-11-14)
5.8.0 (2025-11-14)
- #2502: refactor
Model::$typefrom property-info to type-infoType(ef14213)
- php: bump minimum to php 8.2 (#2611) (95b2057)
- symfony: bumped minimum version for Symfony 7 from
^7.1to^7.2(ef14213)
5.7.1 (2025-11-13)
5.7.0 (2025-11-10)
- 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)
5.6.5 (2025-10-20)
- 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)
5.6.4 (2025-10-17)
- config: migrate xml to php config (#2566) (2b12914)
- swagger-php: conflict with broken version 5.5.0 (#2568) (a9bbfa7)
- deps: bump swagger-ui-dist from 5.29.3 to 5.29.4 in /utils (#2564) (254a487)
- PHPStan v2 (#2572) (3b0abc6)
5.6.3 (2025-10-09)
- 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)
5.6.2 (2025-09-15)
5.6.1 (2025-09-10)
5.6.0 (2025-09-03)
5.5.1 (2025-09-01)
- 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'Made it possible to configure how operation ids are generated.
nelmio_api_doc:
operation_id_generation: always_prependPossible 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
valuewith a list of strings to theAreasannotation/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_annotationhas been deprecated in favor ofwith_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
$contexttoPropertyDescriberInterface::supports()
- Deprecated
nulltype from$optionsinNelmio\ApiDocBundle\Attribute\Model::__construct(). Pass an empty array ([]) instead. - Deprecated
nulltype from$optionsinNNelmio\ApiDocBundle\Attribute\Model::__construct(). Pass an empty array ([]) instead.
- Bumped swagger-ui files from
5.18.1to5.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\Annotationnamespace in favor ofNelmio\ApiDocBundle\Attributenamespace 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
optionsandserializationContextvianelmio_api_doc.models.names. - Fixed
serializationContextnot being applied to nested models.
- Added support to opt out of JMS serializer usage per endpoint by setting
useJmsin 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
- Calling
DocumentationExtension::getExtendedType()has been deprecated in favor ofDocumentationExtension::getExtendedTypes()to align with the deprecation introduced withsymfony/symfonyversion4.2.
- 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- Added support for JMS @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:will be interpreted as appropriate/** * @var int<6, 11> * @var int<min, 11> * @var int<6, max> * @var positive-int * @var negative-int */
minimumandmaximumproperties in the generated OpenAPI specification.
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_idnow automatically gets the area appended.Result in cache keys:nelmio_api_doc: cache: pool: app.cache item_id: nelmio_api_doc.docs areas: default: ... area1: ...
nelmio_api_doc.docs.default&nelmio_api_doc.docs.area1to be used respectively. - Added cache configuration option per area.
Non-configured options will be inherited from
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 ...
nelmio_api_doc.cache. - Fixed vendor extensions (
x-*) from configuration not being outputted in the generated specification.Now results in JSON specification:nelmio_api_doc: documentation: info: title: 'My API' description: 'My API description' x-foo: 'bar'
{ ... "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
oneOfinstead ofallOf.
-
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
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/Resources/config/routing/swaggerui.xml"
prefix: /api/docBecomes:
doc-api:
resource: "@NelmioApiDocBundle/config/routing/swaggerui.xml"
prefix: /api/doc- Added bundle configuration options
nelmio_api_doc.cache.poolandnelmio_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$groupsparameter 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
@SerializedNameannotation support and name converters when using Symfony >= 4.2. - Removed pattern added from the Expression Violation message.
- Added FOSRestBundle 3.x support
- Added
@SWGannotations support at methods level in models
-
Usage of Google Fonts was removed. System fonts
serif/sanswill 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
documentationoption to define how a form field is documented. -
Allow references to config definitions in controllers.
-
Using
@Modelimplicitly in@SWG\Schema,@SWG\Itemsand@SWG\Propertyis deprecated. Useref=@Model()instead.Before:
/** * This was considered as an array of models. * * @SWG\Property(@Model(type=FooClass::class)) */
After:
/** * For an individual object: * @SWG\Property(ref=@Model(type=FooClass::class)) * * For an array: * @SWG\Property(type="array", @SWG\Items(ref=@Model(type=FooClass::class))) */
Config
-
nelmio_api_doc.areasadded 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 forinteger) - Also process phpdoc annotations
SwaggerPHP
- Handle
enumanddefaultproperties from SwaggerPHP annotation - Support
@Securityannotations
Config
-
nelmio_api_doc.routeshas been replaced bynelmio_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.