radebatz/openapi-extras

Extra annotations for OpenApi/swagger-php.

3.1.0 2025-01-09 20:16 UTC

Requires

• php: >=8.1
• psr/log: ^2.0 || ^3.0
• psr/simple-cache: ^1.0 || ^2.0 || ^3.0
• zircote/swagger-php: ^4.11.1 || ^5.0

Requires (Dev)

• composer/package-versions-deprecated: ^1.11
• doctrine/annotations: ^2.0
• friendsofphp/php-cs-fixer: ^3.0
• phpstan/phpstan: ^1.6 || ^2.0
• phpunit/phpunit: ^9.0
• rector/rector: ^1.2 || ^2.0
• vimeo/psalm: ^4.23 || ^5.0

Suggests

• radebatz/openapi-router: Routing adapter for OpenApi annotations.
• radebatz/openapi-verifier: Allows your PHPUnit tests to validate your controller response against your OpenAPI spec.

Conflicts

• symfony/process: >=6, <6.4.14

MIT

• Martin Rademacher

• api
• openapi
• Swagger-PHP

README

Introduction

Extra attributes/annotations and other bits for swagger-php.

Installation

You can use composer or simply download the release.

Composer

The preferred method is via composer. Follow the installation instructions if you do not already have composer installed.

Once composer is installed, execute the following command in your project root to install this library:

composer require radebatz/openapi-extras

Registering the library

Use of the included annotations/attributes requires registration of a custom swagger-php processor. Also, in the case of annotations, the registration of custom aliases / namespaces needs to be done manually.

Using the Builder

When using the OpenApiBuilder no additional registration code is required as the builder will always configure the required MergeControllerDefaults processor.

<?php

use Radebatz\OpenApi\Extras\OpenApiBuilder;

$generator = (new OpenApiBuilder())->build();

// ...

Register library for attributes

<?php

use OpenApi\Generator;
use OpenApi\Processors\BuildPaths;
use Radebatz\OpenApi\Extras\Processors\MergeControllerDefaults;

$generator = new Generator();
$generator->getProcessorPipeline()
            ->insert(new MergeControllerDefaults(), BuildPaths::class);

// ...

Register library for annotations

<?php

use OpenApi\Generator;
use OpenApi\Processors\BuildPaths;
use Radebatz\OpenApi\Extras\Processors\MergeControllerDefaults;

$namespace = 'Radebatz\\OpenApi\\Extras\\Annotations';

$generator = new Generator();
$generator
    ->addNamespace($namespace . '\\')
    ->addAlias('oax', $namespace),
    ->getProcessorPipeline()
    ->insert(new MergeControllerDefaults(), BuildPaths::class);

// ...

Basic usage

OpenApiBuilder

The builder aims to simplify configuring the swagger-php Generator class by implementing explicit methods to configure all default processors. Futhermore, it also adds a new Customizer processor which allows to pre-process all instances of a given OpenApi annotation/attribute by registering callbacks.

<?php declare(strict_types=1);

use OpenApi\Annotations as OA;
use Psr\Log\NullLogger;
use Radebatz\OpenApi\Extras\OpenApiBuilder;

$generator = (new OpenApiBuilder())
                 ->addCustomizer(OA\Info::class, fn (OA\Info $info) => $info->description = 'Foo')
                 ->tagsToMatch(['admin'])
                 ->clearUnused(enabled: true)
                 ->operationIdHashing(enabled: false)
                 ->pathsToMatch(['/api'])
                 ->enumDescription()
                 ->build(new NullLogger());

Controller

The controller annotation may be used to:

• add an optional url prefix to all operations in the class
• share one or more Responses across all operations
• share one or more Header's across all operations
• share one or more Middleware's across all operations

Example for adding the /foo prefix and a 403 response to all operations in the MyController class.

<?php declare(strict_types=1);

use OpenApi\Attributes as OAT;
use Radebatz\OpenApi\Extras\Attributes as OAX;

#[OAX\Controller(prefix: '/foo')]
#[OAT\Response(response: 403, description: 'Not allowed')]
class PrefixedController
{
    #[OAT\Get(path: '/prefixed', operationId: 'prefixed')]
    #[OAT\Response(response: 200, description: 'All good')]
    public function prefixed(): mixed
    {
        return 'prefixed';
    }
}

Middleware

The Middleware annotation is currently not used but will be used by a future version of the openapi-router project.

Middleware annotations allow to share a list of middleware names either individually or across all operations (via the Controller annotation).

<?php declare(strict_types=1);

namespace Radebatz\OpenApi\Extras\Tests\Fixtures\Controllers\Attributes;

use OpenApi\Attributes as OAT;
use Radebatz\OpenApi\Extras\Attributes as OAX;

#[OAX\Controller()]
#[OAX\Middleware([MyFooMiddleware::class])]
class MiddlewareController
{
    #[OAT\Get(path: '/mw', operationId: 'mw')]
    #[OAT\Response(response: 200, description: 'All good')]
    #[OAX\Middleware(['BarMiddleware'])]
    public function mw()
    {
        return 'mw';
    }
}

License

The openapi-extras project is released under the MIT license.