# Using the `Generator`

## Introduction
The `Generator` class is the main entry point into `swagger-php`.

## The `\OpenApi\Generator` class

The `Generator` class provides an object-oriented (and fluent) API to generate OpenApi specs
and allows for easy customization where needed.

## Full example of using the `Generator` class to generate OpenApi specs

```php
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__);

$context = new OpenApi\Context();

$openapi = (new \OpenApi\Generator($logger))
            ->setProcessorPipeline(new \OpenApi\Utils\Pipeline($processors))
            ->setAliases(['MY' => 'My\Annotations'])
            ->setNamespaces(['My\\Annotations\\'])
            ->setAnalyser(new \OpenApi\Analysers\ReflectionAnalyser([new OpenApi\Analysers\DocBlockAnnotationFactory(), new OpenApi\Analysers\AttributeAnnotationFactory()]))
            ->setVersion(\OpenApi\Annotations\OpenApi::VERSION_3_0_0)
            ->generate(['/path1/to/project', $finder], new \OpenApi\Analysis([], $context), $validate);
```

`Aliases` and `namespaces` setting are optional and only required when using annotations.
They allow to customize the parsing of docblocks and are passed through to the underlying `doctrine/annotations` library.

Defaults:
* **aliases**: `['oa' => 'OpenApi\\Annotations']`

  Aliases help to parse annotations. Effectively, they avoid having to write `use OpenApi\Annotations as OA;` in your code
  and make `@OA\property(..)` annotations still work.

* **namespaces**: `['OpenApi\\Annotations\\']`

  Namespaces control which annotation namespaces can be autoloaded automatically. Under the hood this
  is handled by registering a custom loader with the `doctrine annotation library`.


## Basic example
```php
require('"vendor/autoload.php');

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

The `generate()` method does not support the CLI `exclude` and `pattern` options directly.
Instead, a custom Symfony `Finder` class (`SourceFinder`) can be used that understands these options.

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

$openapi = (new \OpenApi\Generator())->generate(new \OpenApi\Utils\SourceFinder(__DIR__, $exclude, $pattern));
```