diff --git a/README.md b/README.md index 7c4c502..99f8174 100644 --- a/README.md +++ b/README.md @@ -5,15 +5,16 @@ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) ## Introduction -Allows to (re-)use [Swagger-PHP](https://github.com/zircote/swagger-php) attributes to configure routes in the -following frameworks: +Allows to (re-)use [Swagger-PHP](https://github.com/zircote/swagger-php) attributes (docblock annotations are deprecated), +to configure routes in the following frameworks: + * [Laravel](https://github.com/laravel/laravel) * [Lumen](https://github.com/laravel/lumen) * [Slim](https://github.com/slimphp/Slim) ## Requirements -* [PHP 8.1 or higher](http://www.php.net/) - depending on framework version. +* [PHP 8.1 or higher](http://www.php.net/) - depending on framework version. ## Installation @@ -34,7 +35,30 @@ After that all required classes should be availabe in your project to add routin ## Basic usage -Example using the `Slim` framework adapter and standard [OpenApi annotations](https://github.com/zircote/swagger-php/tree/main/src/Annotations) only. +Example using the `Slim` framework adapter and standard [OpenApi attributes](https://zircote.github.io/swagger-php/guide/attributes) only. + +**Controller** +```php +write('Get me'); + } +} +``` **index.php** ```php @@ -53,35 +77,8 @@ $app = new App(); $app->run(); ``` -**Controller** -```php -write('Get me'); - } -} -``` - ## Documentation * [Configuration](docs/Configuration.md) -* [Annotation extensions](docs/AnnotationExtensions.md) ## License diff --git a/composer.json b/composer.json index 1ee854e..81ae2b4 100644 --- a/composer.json +++ b/composer.json @@ -43,6 +43,7 @@ "psr/log": "^1.1 || ^2.0 || ^3.0", "psr/simple-cache": "^1.0 || ^2.0 || ^3.0", "radebatz/openapi-extras": "^2.1", + "slim/slim": "^4.14", "zircote/swagger-php": "^4.11.1" }, "require-dev": { diff --git a/docs/AnnotationExtensions.md b/docs/AnnotationExtensions.md deleted file mode 100644 index 366ecd1..0000000 --- a/docs/AnnotationExtensions.md +++ /dev/null @@ -1,125 +0,0 @@ -# Annotation Extensions - -## Default Annotations -By default the router expects only standard [OpenApi annotations](https://github.com/zircote/swagger-php/tree/main/src/Annotations). - -Theses annotations have only limited build in support for advanced routing features. If you feel like -sticking to those the only way to add more options is to use the -[vendor extension](https://swagger.io/specification/#vendorExtensions) system. - -Vendor extensions are OpenApi properties starting with `x-`. Annotations supports this via the `x` annotation property. - -**Vendor extension example:** -```php - ... - - /** - * @OA\Get( - * path="/login", - * x={ - * "name": "login", - * "middleware": {"auth", "verified"} - * }, - * @OA\Response(response="200", description="All good") - * ) - */ -``` - -The example showcases the two vendor extensions that the router supports: -* **name** - - The name property is used to bind a (unique) name to each route which later can be used to lookup - the route (for example to generate a url). - - name binding is supported by all adapters. - -* **middleware** - - [Middleware](https://www.php-fig.org/psr/psr-15/) is a concept that only some frameworks support. In those cases - one or more middleware can be attached to a route as shown above. - - Middleware binding is supported by all adapters. - -As an alternative to using the x-name property it is also possible to use the standard `operationId` property to configure -a route name. - -**NOTE:** It is worth noticing that by default this property is set to `[Controller class]::[method name]` by the swagger-php -library. If you do not wish to use `operationId` it is recommended to disable using it as name value for route binding -(see the global `OPTION_OA_OPERATION_ID_AS_NAME` config option) - -## Extended Annotations -### Operations -As an alternative to the above syntax the openapi-router project provides its own (extended) versions of annotations for -all operations (`'get', 'post', 'put', 'patch', 'delete', 'options', 'head'`). - -These are registered with a namespace alias of `@OSX`. - -**Extended annotation example:** -```php - ... - - /** - * @OAX\Get( - * path="/foo", - * operationId="foo", - * @OA\Response(response="200", description="All good") - * ) - */ -``` - -### `Controller` Annotation -openapi-router also provides a `Controller` annotation that can be used to: -* apply a path prefix to all controller routes -* configure middlewares shared by all controller routes -* configure responses shared by all controller routes - -This annotation can be used with both standard and extended operation annotations. - -**Controller annotation example:** -```php -... - -/** - * @OAX\Controller( - * prefix="api/v1", - * middleware={"auth"}, - * @OA\Response(response=401, description="Not Authenticated") - * ) - */ -class UserController extends Controller -{ - /** - * @OA\Get( - * path="user/{id}/delete", - * operationId="transfer", - * middleware={"role:admin"}, - * @OA\Response(response="200", description="All good") - * ) - */ - public static function delete($request, $response, $id) - { - // delete user - } -``` - -## Attributes -As of PHP 8.1 swagger-php and openapi-router also allow to use PHP attributes instead of docblock annotations. -Names and features are the same with one exception - for middleware there is a new attribute `Middleware` which avoid having to -use the included customized swagger-php operation annotations. - -Here is an example taken from the test suite: -```php - -use Radebatz\OpenApi\Routing\Annotations as OAX; - - class AttributeController - { - #[OA\Get(path: '/prefixed', x: ['name' => 'attributes'])] - #[OA\Response(response: 200, description: 'All good')] - #[OAX\Middleware([BMiddleware::class])] - public function prefixed() - { - return FakeResponse::create('Get fooya'); - } - } -``` diff --git a/docs/Configuration.md b/docs/Configuration.md index d5a1a82..21f677a 100644 --- a/docs/Configuration.md +++ b/docs/Configuration.md @@ -4,7 +4,7 @@ The `OpenApiRouter` class takes an array (map) as optional third constructor argument which allows to customise its behaviour. -All option names (keys) are defined as class constants. +All option names (keys) are defined as class constants in `Radebatz\OpenApi\Routing\OpenApiRouter`. **`OPTION_RELOAD`** --- @@ -12,6 +12,8 @@ Enforces loading of route annotations on each request. Typically you want this turned off on production. Requires a cache confgured (annotation caching) or caching support implemented by the used adapter. +**Note**: When using a framework it is recommended to rely on the framework caching rather than using the (simple) build in cache. + Default: `true` **`OPTION_CACHE`** @@ -26,21 +28,24 @@ Default: `null` --- Controls whether to inject a default `@OA\Info` instance while scanning. -This can be useful if your top level OpenApi annotation is inside the scanned folder hierarchy. +This can be useful for testing or small projects. -Default: `true` +Default: `false` **`OPTION_OA_OPERATION_ID_AS_NAME`** --- -Controls whether to default the custom (x-) name property to the `operationId`. +Controls whether to use the configured `operationId` as the route name. If disabled the adapter will look for a vendor property +`x-name` on the operation (`Get`, `Post`, etc.) attribute. + +Allows to set the route name via the standard `operationId` rather than the vendor `x-name`. -Allows to set the route name via the standard `operationId` rather than `x-name`. -By default the `operationId` is populated with the controller (class/method) for the route. +**Note**: The default for `operationId` in `swagger-php` is to generate an operationId and hash it if it is explicitely set. generated Default: `true` ### Example use ```php +