Processor Reference

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

For improvements head over to GitHub and create a PR ;)

Processors are listed in the default order of execution.

Processor Configuration

Command line

The -c option takes a name/value pair: the processor name (starting lowercase) and the option name, separated by a dot (.).

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

> ./vendor/bin/openapi -c operationId.hash=true src
> ./vendor/bin/openapi -c pathFilter.tags[]=/pets/ -c pathFilter.tags[]=/store/ src

Programmatically with PHP

Configuration can be set using the Generator::setConfig() method. Keys can either be the same as on the command line or be broken down into nested arrays.

(new Generator())
    ->setConfig([
        'operationId.hash' => true,
        'pathFilter' => [
            'tags' => [
                '/pets/',
                '/store/',
            ],
        ],
    ]);

Default Processors

DocBlockDescriptions

Checks if the annotation has a summary and/or description property and uses the text in the comment block (above the annotations) as summary and/or description.

Use <code>null</code>, for example <code>@Annotation(description=null)</code>, if you don't want the annotation to have a description.

MergeIntoOpenApi

Merge all <code>@OA\OpenApi</code> annotations into one.

Config settings

• mergeIntoOpenApi.mergeComponents : bool · default: false
  If set to <code>true</code> allow multiple @OA\Components annotations to be merged.

MergeIntoComponents

Merge reusable annotation into <code>@OA\Schemas</code>.

ExpandClasses

Iterate over the chain of ancestors of a schema and:

• if the ancestor has a schema => inherit from the ancestor if it has a schema (allOf) and stop.
• else => merge ancestor properties into the schema.

ExpandInterfaces

Look at all (direct) interfaces for a schema and:

• merge interfaces annotations/methods into the schema if the interface does not have a schema itself
• inherit from the interface if it has a schema (allOf).

ExpandTraits

Look at all (direct) traits for a schema and:

• merge trait annotations/methods/properties into the schema if the trait does not have a schema itself
• inherit from the trait if it has a schema (allOf).

ExpandEnums

Expands PHP enums.

Determines <code>schema</code>, <code>enum</code> and <code>type</code>.

Config settings

• expandEnums.enumNames : string · default: null
  Specifies the name of the extension variable where backed enum names will be stored. Set to <code>null</code> to avoid writing backed enum names.

  Example: <code>->setEnumNames('enumNames')</code> yields:

  yamlCopy

    x-enumNames:
      - NAME1
      - NAME2
  

AugmentSchemas

Use the Schema context to extract useful information and inject that into the annotation.

Merges properties.

AugmentRequestBody

Use the RequestBody context to extract useful information and inject that into the annotation.

AugmentProperties

Use the property context to extract useful information and inject that into the annotation.

AugmentDiscriminators

Use the property context to extract useful information and inject that into the annotation.

BuildPaths

Build the openapi->paths using the detected <code>@OA\PathItem</code> and <code>@OA\Operation</code> (<code>@OA\Get</code>, etc).

AugmentParameters

Augments shared and operations parameters from docblock comments.

Config settings

• augmentParameters.augmentOperationParameters : bool · default: true
  If set to <code>true</code> try to find operation parameter descriptions in the operation docblock.

AugmentRefs

AugmentItems

Use the Schema context to extract useful information and inject that into the annotation.

Merges properties.

MergeJsonContent

Split JsonContent into Schema and MediaType.

MergeXmlContent

Split XmlContent into Schema and MediaType.

AugmentMediaType

Augment media type encodings.

OperationId

Generate the OperationId based on the context of the OpenApi annotation.

Config settings

• operationId.hash : bool · default: true
  If set to <code>true</code> generate ids (md5) instead of clear text operation ids.

CleanUnmerged

PathFilter

Allows to filter endpoints based on tags and/or path.

If no <code>tags</code> or <code>paths</code> filters are set, no filtering is performed.

All filter (regular) expressions must be enclosed within delimiter characters as they are used as-is.

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.

CleanUnusedComponents

Tracks the use of all <code>Components</code> and removed unused schemas.

Config settings

• cleanUnusedComponents.enabled : bool · default: false
  Enables/disables the <code>CleanUnusedComponents</code> processor.

AugmentTags

Ensures that all tags used on operations also exist in the global <code>tags</code> list.

Config settings

• augmentTags.whitelist : array · default: []
  Whitelist tags to keep even if not used. <code>*</code> may be used to keep all unused.
• augmentTags.withDescription : bool · default: true
  Enables/disables generation of default tag descriptions.