🧪 Processing Modes

Swagger-php supports three processing modes that control how your source code is transformed into an OpenAPI document. Each mode uses a different internal pipeline, but all produce the same OpenAPI output format.

Overview

	Classic	Hybrid	Spec
Status	Stable	Beta	Beta
Attributes	OpenApi\Attributes	OpenApi\Attributes	OpenApi\Spec
Annotations	Yes	Yes	No
Pipeline	Generator → Processors	Generator → HybridBridge → Augmenters → Compiler	Assembler → Augmenters → Compiler
PHP requirement	8.1+	8.1+	8.1+
Best for	Existing projects	Gradual migration	New projects

Classic (default)

The classic mode scans source files for OpenApi\Attributes (and legacy OpenApi\Annotations) and assembles the OpenAPI document via the Generator pipeline with its processor chain.

This is the stable, production-ready mode and the default for all existing projects.

use OpenApi\Builder;

$result = (new Builder())
    ->addSource('src/')
    ->build();

$result->toYaml();

Classic mode gives you access to the full Generator API including custom processors, analysers, and configuration options via withGenerator().

Spec (beta)

Spec mode is a ground-up reimplementation of the pipeline using pure PHP 8.1+ attributes from the OpenApi\Spec namespace. It introduces:

• Typed DTOs — attributes are simple data containers with constructor-promoted properties
• Slot-map nesting — explicit merge()/contains() maps replace reflection-based nesting resolution
• Grouped augmenters — a three-phase pipeline (resolve → reduce → augment) that's easy to extend and configure
• Version-aware compilers — separate compilers for OpenAPI 3.0, 3.1, and 3.2

use OpenApi\Builder;
use OpenApi\Builder\Mode;

$result = (new Builder())
    ->setMode(Mode::SPEC)
    ->addSource('src/')
    ->build();

$result->toYaml();

Spec mode uses the OpenApi\Spec namespace (use OpenApi\Spec as OA;) with a cleaner attribute API. See Using Spec Attributes for a full guide.

Beta

Spec mode is feature-complete but still beta. The attribute API may evolve based on feedback before being promoted to default in a future major version.

Hybrid (beta)

Hybrid mode uses the classic Generator for scanning (so your existing OpenApi\Attributes annotations work unchanged), then bridges the result into the spec pipeline's augmenters and compilers.

This gives you access to the new augmenter pipeline — with its cleaner extension model and version-aware compilation — without rewriting any attribute code.

use OpenApi\Builder;
use OpenApi\Builder\Mode;

$result = (new Builder())
    ->setMode(Mode::HYBRID)
    ->addSource('src/')
    ->build();

$result->toYaml();

Hybrid mode is the recommended transition path for existing projects that want to benefit from the new pipeline incrementally.

Switching modes

CLI

./vendor/bin/openapi src/ --mode spec -o openapi.yaml
./vendor/bin/openapi src/ --mode hybrid -o openapi.yaml

PHP

use OpenApi\Builder;
use OpenApi\Builder\Mode;

$builder->setMode(Mode::SPEC);
// or: $builder->setMode('spec');

Behavioral differences

The three modes produce equivalent OpenAPI output for the same logical API. However, there are some differences in how they process source code:

Behavior	Classic	Hybrid	Spec
Annotation support (/** @OA\... */)	Yes	Yes	No
MergeJsonContent / MergeXmlContent	Yes	Yes	Yes (via OA\MediaType\Json)
Processor chain (withGenerator())	Yes	Scanning only (MergeJsonContent/MergeXmlContent)	No
Augmenter pipeline (withAugmenters())	No	Yes	Yes
Version-aware compilation	No (single serializer)	Yes	Yes

Migration path

The recommended migration path is:

1. Classic → Hybrid — change setMode(Mode::HYBRID) and verify output is unchanged. No code changes needed. This gives you access to the augmenter pipeline.

2. Hybrid → Spec — when starting new code, use OpenApi\Spec attributes. Existing OpenApi\Attributes code continues to work via hybrid mode.

3. Full Spec — once all code uses OpenApi\Spec attributes, switch to setMode(Mode::SPEC) for the cleanest pipeline.

Version timeline

• v6 — spec/hybrid ship as opt-in beta. Classic remains default.
• v7 — hybrid becomes the default mode. Classic still available. setMode() and all classic code deprecated
• v8 — classic removed. setMode() removed. Spec becomes default. spec code might move to OpenApi\Attributes.