Swagger-PHP

Appearance

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.

shell
> ./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.

php
(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 null, for example @Annotation(description=null), if you don't want the annotation to have a description.

MergeIntoOpenApi ​

Merge all @OA\OpenApi annotations into one.

Config settings ​

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

MergeIntoComponents ​

Merge reusable annotation into @OA\Schemas.

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 schema, enum and type.

Config settings ​

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

    Example: ->setEnumNames('enumNames') yields:

    yaml
      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 @OA\PathItem and @OA\Operation (@OA\Get, etc).

AugmentParameters ​

Augments shared and operations parameters from docblock comments.

Config settings ​

  • augmentParameters.augmentOperationParameters : bool · default: true
    If set to true 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 true generate ids (md5) instead of clear text operation ids.

CleanUnmerged ​

PathFilter ​

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

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

CleanUnusedComponents ​

Tracks the use of all Components and removed unused schemas.

Config settings ​

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

AugmentTags ​

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

Config settings ​

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