Augmenter Reference

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

For improvements head over to GitHub 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.

> ./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().

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

Default Augmenters

Inheritance

Handle all scenarios related to PHP inheritance.

Delegates to:

• Inheritance\Schemas
• Inheritance\Operations

Names

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

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 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. x-enum-varnames).

Shortcuts

Resolves shortcut attributes.

Handles:

• OA\MediaType\Json
• OA\MediaType\Xml
• OA\Schema\Items

PathItems

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

Walks the class hierarchy to compose path prefixes from ancestor PathItems, 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.

Types

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

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

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 tags to include.
• pathFilter.paths : array · default: []
  A list of regular expressions to match paths to include.

Cleanup

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

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

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

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

Config settings

• operationIds.hash : bool · default: true
  If set to true generate ids (md5) instead of clear text operation ids.

Tags

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

Generates a description for enum-based properties.

Config settings

• enumDescriptions.enabled : bool · default: false
  Enables/disables generation of descriptions for enum based properties.