nelmio/api-doc-bundle

• 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 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 int<6, 11>
     * @var int<min, 11>
     * @var int<6, max>
     * @var positive-int
     * @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/Resources/config/routing/swaggerui.xml"
    prefix: /api/doc

Becomes:

doc-api:
    resource: "@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.