Re-useable annotations for swagger-php.
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
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.
<?php
use OpenApi\Generator;
use OpenApi\Processors\BuildPaths;
use Radebatz\OpenApi\Extras\Processors\MergeControllerDefaults;
$generator = new Generator();
// ...
$generator->addProcessor(new MergeControllerDefaults(), BuildPaths::class);
// ...
<?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);
// ...
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';
}
}
The Middleware
annotation is currently not used but will be used by a future version
of the openappi-router project.
The openapi-extras project is released under the MIT license.