radebatz/openapi-extras

Extra annotations for OpenApi/swagger-php.

1.0.0 2022-12-22 23:41 UTC

Requires

• php: >=7.4
• doctrine/annotations: < 1.14
• psr/simple-cache: ^1.0 || ^2.0 || ^3.0
• zircote/swagger-php: ^4.5.3

Requires (Dev)

• composer/package-versions-deprecated: ^1.11
• friendsofphp/php-cs-fixer: ^2.17 || ^3.0
• phpstan/phpstan: ^1.6
• phpunit/phpunit: >=8
• vimeo/psalm: ^4.23

MIT

• Martin Rademacher

• api
• openapi
• Swagger-PHP

README

Introduction

Re-useable annotations 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 processor. Also, in the case of annotations the registration of the custom alias / namespace used.

Register library for attriutes

<?php

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

$generator = new Generator();

// ...

$generator->addProcessor(new MergeControllerDefaults(), BuildPaths::class);

// ...

Register library for annotations

<?php

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

$generator = new Generator();

// ...

$namespace = 'Radebatz\\OpenApi\\Extras\\Annotations';
$generator
    ->addNamespace($namespace . '\\')
    ->addAlias('oax', $namespace),
    ->addProcessor(new MergeControllerDefaults(), BuildPaths::class);

// ...

Basic usage

Controller

The controller annotation may be used on class level to add an optional prefix to all operations of that controller class.

Also, it can be used to add default responses to all endpoints.

Example 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 openappi-router project.

License

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