coupon-admin/vendor/zircote/swagger-php/docs/Generator-migration.md

Using the Generator

Motivation

Code to perform a fully customized scan using swagger-php so far required to use 3 separate static elements:

1. \OpenApi\scan()

   The function to scan for OpenApi annotations.

2. Analyser::$whitelist

   List of namespaces that should be detected by the doctrine annotation parser.

3. Analyser::$defaultImports

   Imports to be set on the used doctrine DocParser. Allows to pre-define annotation namespaces. The @OA namespace, for example, is configured as ['oa' => 'OpenApi\\Annotations'].

The new Generator class provides an object-oriented way to use swagger-php and all its aspects in a single place.

The \OpenApi\scan() function

For a long time the \OpenApi\scan() function was the main entry point into using swagger-php from PHP code.

/**
  * Scan the filesystem for OpenAPI annotations and build openapi-documentation.
  *
  * @param array|Finder|string $directory The directory(s) or filename(s)
  * @param array               $options
  *                                       exclude: string|array $exclude The directory(s) or filename(s) to exclude (as absolute or relative paths)
  *                                       pattern: string       $pattern File pattern(s) to scan (default: *.php)
  *                                       analyser: defaults to StaticAnalyser
  *                                       analysis: defaults to a new Analysis
  *                                       processors: defaults to the registered processors in Analysis
  *
  * @return OpenApi
  */
  function scan($directory, $options = []) { /* ... */ }

Using it looked typically something like this:

require("vendor/autoload.php");

$openapi = \OpenApi\scan(__DIR__, ['exclude' => ['tests'], 'pattern' => '*.php']);

The two configuration options for the underlying Doctrine doc-block parser Analyser::$whitelist and Analyser::$defaultImports are not part of this function and need to be set separately.

Being static this means setting them back is the callers responsibility and there is also the fact that some of the Doctrine configuration currently can not be reverted easily.

Therefore, having a single side-effect free way of using swwagger-php seemed like a good idea...

The \OpenApi\Generator class

The new Generator class can be used in object-oriented (and fluent) style which allows for easy customization if needed.

In that case to actually process the given input files the non-static method generate() is to be used.

Full example of using the Generator class to generate OpenApi specs.

require("vendor/autoload.php");

$validate = true;
$logger = new \Psr\Log\NullLogger();
$processors = [/* my processors */];
$finder = \Symfony\Component\Finder\Finder::create()->files()->name('*.php')->in(__DIR__);

$openapi = (new \OpenApi\Generator($logger))
            ->setProcessors($processors)
            ->setAliases(['MY' => 'My\Annotations'])
            ->setAnalyser(new \OpenApi\StaticAnalyser())
            ->setNamespaces(['My\\Annotations\\'])
            ->generate(['/path1/to/project', $finder], new \OpenApi\Analysis(), $validate);

The aliases property corresponds to the now also deprecated static Analyser::$defaultImports, namespaces to Analysis::$whitelist.

Advantages:

• The Generator code will handle configuring things as before in a single place
• Static settings will be reverted to defaults once finished
• The get/set methods allow for using type hints
• Static configuration is deprecated and can be removed at some point without code changes
• Build in support for PSR logger
• Support for Symfony Finder, \SplInfo and file/directory names (`string) as source.

The minimum code required, using the generate() method, looks quite similar to the old scan() code:

    /**
     * Generate OpenAPI spec by scanning the given source files.
     *
     * @param iterable      $sources  PHP source files to scan.
     *                                Supported sources:
     *                                * string - file / directory name
     *                                * \SplFileInfo
     *                                * \Symfony\Component\Finder\Finder
     * @param null|Analysis $analysis custom analysis instance
     * @param bool          $validate flag to enable/disable validation of the returned spec
     */
    public function generate(iterable $sources, ?Analysis $analysis = null, bool $validate = true): \OpenApi\OpenApi { /* ... */ }

require("vendor/autoload.php");

$openapi = (new \OpenApi\Generator())->generate(['/path1/to/project']);

For those that want to type even less and keep using a plain array to configure swagger-php there is also a static version:

<?php
require("vendor/autoload.php");

$openapi = \OpenApi\Generator::scan(['/path/to/project']);

header('Content-Type: application/x-yaml');
echo $openapi->toYaml();

Note: While using the same name as the old scan() function, the Generator::scan method is not 100% backwards compatible.

    /**
     * Static  wrapper around `Generator::generate()`.
     *
     * @param iterable $sources PHP source files to scan.
     *                          Supported sources:
     *                          * string
     *                          * \SplFileInfo
     *                          * \Symfony\Component\Finder\Finder
     * @param array    $options
     *                          aliases:    null|array                    Defaults to `Analyser::$defaultImports`.
     *                          namespaces: null|array                    Defaults to `Analyser::$whitelist`.
     *                          analyser:   null|StaticAnalyser           Defaults to a new `StaticAnalyser`.
     *                          analysis:   null|Analysis                 Defaults to a new `Analysis`.
     *                          processors: null|array                    Defaults to `Analysis::processors()`.
     *                          validate:   bool                          Defaults to `true`.
     *                          logger:     null|\Psr\Log\LoggerInterface If not set logging will use \OpenApi\Logger as before.
     */
    public static function scan(iterable $sources, array $options = []): OpenApi { /* ... */ }

Most notably the exclude and pattern keys are no longer supported. Instead, a Symfony Finder instance can be passed in as source directly (same as with Generator::generate()).

If needed, the \OpenApi\Util class provides a builder method that allows to keep the status-quo

$exclude = ['tests'];
$pattern = '*.php';

$openapi = \OpenApi\Generator::scan(\OpenApi\Util::finder(__DIR__, $exclude, $pattern));

// same as

$openapi = \OpenApi\scan(__DIR__, ['exclude' => $exclude, 'pattern' => $pattern]);