Migrating to v4

Overview

• As of PHP 8.1 annotations may be used as PHP attributes instead. That means all references to annotations in this document also apply to attributes.
• If you haven't switched to attributes yet, the Doctrine annotations library must be installed manually: composer require doctrine/annotations
• Annotations now must be associated with a structural element (class, trait, interface), a method, property or const.
• A new annotation PathParameter was added for improved framework support.
• A new annotation Attachable was added to simplify custom processing. Attachable can be used to attach arbitrary data to any given annotation.
• Deprecated elements have been removed
  • \Openapi\Analysis::processors()
  • \Openapi\Analyser::$whitelist
  • \Openapi\Analyser::$defaultImports
  • \Openapi\Logger
• Legacy support is available via the previous TokenAnalyser
• Improvements to the Generator class

Annotations as PHP attributes

While PHP attributes have been around since PHP 8.0 they were lacking the ability to be nested. This changes with PHP 8.1 which allows to use new in initializers.

Swagger-php attributes also make use of named arguments, so attribute parameters can be (mostly) typed. There are some limitations to type hints which can only be resolved once support for PHP 7.x is dropped.

Using annotations

use OpenApi\Annotations as OA;

/**
 * [@OA](https://github.com/OA)\Info(
 *   version="1.0.0",
 *   title="My API",
 *   [@OA](https://github.com/OA)\License(name="MIT"),
 *   [@OA](https://github.com/OA)\Attachable()
 * )
 */
class OpenApiSpec
{
}

Using attributes

use OpenApi\Attributes as OA;

#[OA\Info(
    version: '1.0.0',
    title: 'My API',
    attachables: [new OA\Attachable()]
)]
#[OA\License(name: 'MIT')]
class OpenApiSpec
{
}

Optional nesting

One of the few differences between annotations and attributes visible in the above example is that the OA\License attribute is not nested within OA\Info. Nesting of attributes is possible and required in certain cases however, in cases where there is no ambiguity attributes may be all written on the top level and swagger-php will do the rest.

Annotations must be associated with a structural element

The (now legacy) way of parsing PHP files meant that docblocks could live in a file without a single line of actual PHP code.

PHP Attributes cannot exist in isolation; they need code to be associated with and then are available via reflection on the associated structural element. In order to allow to keep supporting annotations and the code simple it made sense to treat annotations and attributes the same in this respect.

The PathParameter annotation

As annotation this is just a short form for

   [@OA](https://github.com/OA)\Parameter(in='body')

Things get more interesting when it comes to using it as attribute, though. In the context of a controller you can now do something like

class MyController
{
    #[OA\Get(path: '/products/{product_id}')]
    public function getProduct(
        #[OA\PathParameter] string $product_id)
    {
    }
}

Here it avoids having to duplicate details about the $product_id parameter and the simple use of the attribute will pick up typehints automatically.

The Attachable annotation

Technically these were added in version 3.3.0, however they become really useful only with version 4.

The attachable annotation is similar to the OpenApi vendor extension x=. The main difference are that

1. Attachables allow complex structures and strong typing
2. Attachables are not added to the generated spec.

Their main purpose is to make customizing swagger-php easier by allowing to add arbitrary data to any annotation.

One possible use case could be custom annotations. Classes extending Attachable are allowed to limit the allowed parent annotations. This means it would be easy to create a new attribute to flag certain endpoints as private and exclude them under certain conditions from the spec (via a custom processor).

Removed deprecated elements

\Openapi\Analysis::processors()

Processors have been moved into the Generator class incl. some new convenience methods.

\Openapi\Analyser::$whitelist

This has been replaced with the Generator namespaces property.

\Openapi\Analyser::$defaultImports

This has been replaced with the Generator aliases property.

\Openapi\Logger

This class has been removed completely. Instead, you may configure a PSR-3 logger.

Improvements to the Generator class

The removal of deprecated static config options means that the Generator class now is the main entry point into swagger-php when used programmatically.

To make the migration as simple as possible a new Generator::withContext(callable) has been added. This allows to use parts of the library (an Analyser instance, for example) within the context of a Generator instance.

Example:

$analyser = createMyAnalyser();

$analysis = (new Generator())
    ->addAlias('fo', 'My\\Attribute\\Namespace')
    ->addNamespace('Other\\Annotations\\')
    ->withContext(function (Generator $generator, Analysis $analysis, Context $context) use ($analyser) {
        $analyser->setGenerator($generator);
        $analysis = $analyser->fromFile('my_code.php', $context);
        $analysis->process($generator->getProcessors());

        return $analysis;
    });