examples

Specs

Collection of code/annotation examples and their corresponding OpenAPI specs generated using swagger-php.

• api - Basic API
• misc
• nesting - Nested schemas and class hierarchies
• petstore - Classic petstore
• polymorphism - Using @OA\Discriminator
• using interfaces
• using-links
• using refs
• using traits
• webhooks - Using @OA\Webhook

Custom augmenters

Augmenters enrich the specification in spec and hybrid mode. Writing a custom augmenter is the way to extend that pipeline.

An augmenter implements PipeInterface: group() names the phase it runs in, and __invoke() receives the Specification:

<?php
...
use OpenApi\Augmenter\Group;
use OpenApi\Utils\PipeInterface;
...

class MyCustomAugmenter implements PipeInterface
{
    public function group(): string|\BackedEnum
    {
        return Group::Augment;
    }

    public function __invoke(mixed $payload): mixed
    {
        // custom augmenting

        return $payload;
    }
}

It is added with Builder::withAugmenters(). Each example has a scan.php doing that, and the yaml it generates.

• schema-query-parameter augmenter

  An augmenter that takes a vendor extension naming a class, and adds each property of that class's schema as a query parameter to the operation.

• sort-components augmenter

  An augmenter that sorts schema components, so they appear in alphabetical order.

Custom processors

Warning

Processors are part of the classic pipeline, which is deprecated in 7.0 and removed in 8.0. The augmenter examples above do the same in spec and hybrid mode.

Processors implement the various steps involved in converting the annotations collected into an OpenAPI spec.

Writing a custom processor is the way to extend the classic pipeline.

Processors are expected to implement the __invoke() method expecting the current Analysis object as single parameter:

<?php
...
use OpenApi\Analysis;
...

class MyCustomProcessor
{
    public function __invoke(Analysis $analysis)
    {
        // custom processing
    }
}

• schema-query-parameter processor

  A processor that takes a vendor tag (expecting a schema #ref) and injects all properties of that given schema as query parameter to the request definition.

• sort-components processor

  A processor that sorts components, so they appear in alphabetical order.