# Augmenter Reference

This page is generated automatically from the `swagger-php` sources.

For improvements head over to [GitHub](https://github.com/zircote/swagger-php) and create a PR ;)


Augmenters enrich the collected specification with inferred data before compilation.
They run in three groups — **resolve** (type inference, refs), **reduce** (filtering, cleanup),
and **augment** (docblocks, operation ids, tags) — and are listed below in execution order.

Augmenters are part of the spec-attributes pipeline (`--mode spec` or `--mode hybrid`).

## Augmenter Configuration

### Command line
The `-c` option takes a name/value pair: the augmenter name (starting lowercase)
and the option name, separated by a dot (`.`).

To list the available augmenter names and options use `-D`. It still requires a
source path, e.g. `./vendor/bin/openapi --mode spec -D src`. Unknown keys are
reported as warnings.

```shell
> ./vendor/bin/openapi --mode spec -c operationIds.hash=true src
> ./vendor/bin/openapi --mode spec -c pathFilter.tags[]=/pets/ -c pathFilter.tags[]=/store/ src
```

### Programmatically with PHP
Configuration can be set using the `Builder::withAugmenters()` method to access the pipeline
and configure individual augmenters via `Pipeline::get()`.

```php
(new Builder())
    ->withAugmenters(function ($pipeline) {
        $pipeline->get(Augmenter\OperationIds::class)->setHash(true);
        $pipeline->get(Augmenter\PathFilter::class)->setTags(['/pets/', '/store/']);
    });
```

## Default Augmenters

### [Inheritance](https://github.com/zircote/swagger-php/tree/master/src/Augmenter/Inheritance.php)

Handle all scenarios related to PHP inheritance.

Delegates to:
- Inheritance\Schemas
- Inheritance\Operations

### [Names](https://github.com/zircote/swagger-php/tree/master/src/Augmenter/Names.php)

Infers component keys from PHP reflectors when not explicitly set.

A component declared on a class is named after that class, so it can be referenced by
class name. Declared anywhere else — a method, a parameter — the class reflector belongs
to the *declaring* class, whose name is already taken by that class's own component, so
nothing is inferred and the component stays inline.

A parameter is the one exception: its `name` is its identity in OpenAPI, so a parameter
component is keyed by it wherever it was declared, and falls back to the class name only
when it has no name either.

### [Enums](https://github.com/zircote/swagger-php/tree/master/src/Augmenter/Enums.php)

Expands PHP enums into schema enum values.

For schemas attached to a PHP enum, determines schema name, type, and enum values.
Also resolves UnitEnum instances and enum class-strings in any schema's or server
variable's enum array.

Rules for name vs. value:
- Unit enums (not backed): always use case names, type becomes "string"
- Backed enums without explicit schema type: use case names, type becomes "string"
- Backed enums with schema type matching backing type (int→"integer", string→"string"):
  use backing values, type preserved
- Backed enums with schema type NOT matching backing type: use case names

#### Config settings
- **enums.enumNames** : `string` · default: `null`  
  If set, stores enum case names in a vendor extension with this key (e.g. <code>x-enum-varnames</code>).

### [Shortcuts](https://github.com/zircote/swagger-php/tree/master/src/Augmenter/Shortcuts.php)

Resolves shortcut attributes.

Handles:
* `OA\MediaType\Json`
* `OA\MediaType\Xml`
* `OA\Schema\Items`

### [PathItems](https://github.com/zircote/swagger-php/tree/master/src/Augmenter/PathItems.php)

Resolves PathItem prefixes, clones metadata to operations, and sets path-level output.

Composes path prefixes from the PathItems governing each operation's class, prepends them
to operation paths, clones tags/security/responses to operations that don't declare their
own, and marks PathItems that have spec-level output (parameters, summary, description,
servers) with their resolved path.

The ancestor walk itself belongs to `Specification\PathItemHierarchy`.

### [Types](https://github.com/zircote/swagger-php/tree/master/src/Augmenter/Types.php)

Infers schema type, format, nullable, items, etc. from PHP type declarations and docblocks.

Walks all properties and parameters in the specification and fills their schema
fields from the attached reflector's type information.

### [Refs](https://github.com/zircote/swagger-php/tree/master/src/Augmenter/Refs.php)

Resolves FQCN-based $ref values to JSON Reference paths.

Builds a map of class names to their component paths and rewrites
any $ref that looks like a FQCN into the proper #/components/... path.

### [PathFilter](https://github.com/zircote/swagger-php/tree/master/src/Augmenter/PathFilter.php)

Filters operations by tag and/or path patterns.

If no tags or paths filters are set, no filtering is performed.
All filter expressions must be valid regular expressions (with delimiters).

#### Config settings
- **pathFilter.tags** : `array` · default: `[]`  
  A list of regular expressions to match <code>tags</code> to include.
- **pathFilter.paths** : `array` · default: `[]`  
  A list of regular expressions to match <code>paths</code> to include.

### [Cleanup](https://github.com/zircote/swagger-php/tree/master/src/Augmenter/Cleanup.php)

Removes unreferenced components from the specification.

Iterates multiple times to catch nested dependencies (a schema only
referenced by another unused schema should also be removed).

Removal is silent, with one exception: a response component keyed by a status code is
reported, because it is a response that was meant to nest into an operation.

#### Config settings
- **cleanup.enabled** : `bool` · default: `true`  
  Enables/disables removal of unreferenced components.

### [MediaTypes](https://github.com/zircote/swagger-php/tree/master/src/Augmenter/MediaTypes.php)

Promotes property encodings and re-keys MediaType encoding lists by property name.

Promotes `OA\Encoding` definitions from `OA\Property\Encoded` properties to their
parent MediaType, then re-keys the encoding list as an associative array keyed by
property name (the format the compiler expects).

### [Docblocks](https://github.com/zircote/swagger-php/tree/master/src/Augmenter/Docblocks.php)

Fills summary, description, and deprecated from PHP docblock comments.

Walks all attributes in the specification that have summary/description
properties and populates them from the reflector's docblock when not
explicitly set.

### [OperationIds](https://github.com/zircote/swagger-php/tree/master/src/Augmenter/OperationIds.php)

Generates operationId for operations that don't have one explicitly set.

#### Config settings
- **operationIds.hash** : `bool` · default: `true`  
  If set to <code>true</code> generate ids (md5) instead of clear text operation ids.

### [Tags](https://github.com/zircote/swagger-php/tree/master/src/Augmenter/Tags.php)

Ensures all tags used on operations exist in the global tags list.

Adds missing Tag objects for any tag name referenced by operations.
Removes unused declared tags unless whitelisted.

#### Config settings
- **tags.whitelist** : `array` · default: `[]`  
  Whitelist tags to keep even if not used. Use '*' to keep all.
- **tags.withDescription** : `bool` · default: `true`  
  Enables/disables generation of default tag descriptions.

### [EnumDescriptions](https://github.com/zircote/swagger-php/tree/master/src/Augmenter/EnumDescriptions.php)

Generates a description for enum-based properties.

#### Config settings
- **enumDescriptions.enabled** : `bool` · default: `false`  
  Enables/disables generation of descriptions for enum based properties.