radebatz / openapi-extras
Extra annotations for OpenApi/swagger-php.
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
This package is auto-updated.
Last update: 2023-09-05 04:43:19 UTC
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.