update docs

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
+<?php
+
+namespace MyApp\Controllers\V1;
+
+use OpenApi\Attributes as OA;
+use Radebatz\OpenApi\Extras\Attributes as OAX;
+
+/* Things shared by all endpoints in this controller.*/
+#[OAX\Controller(prefix: '/api/v1')]
+#[OA\Response(response: 200, description: 'OK')]
+#[OAX\Middleware(names: ['auth', 'admin'])]
+class GetController
+{
+    #[OA\Get(path: '/getme', operationId: 'getme')]
+    #[OA\Response(response: 400, description: 'Not good enough')]
+    public function getme($request, $response) {
+        return $response->write('Get me');
+    }
+}
+```
 
 **index.php**
 ```php
@@ -53,35 +77,8 @@ $app = new App();
 $app->run();
 ```
 
-**Controller**
-```php
-<?php
-
-namespace MyApp\Controllers;
-
-use OpenApi\Annotations as OA;
-
-class GetController
-{
-
-    /**
-     * @OA\Get(
-     *     path="/getme",
-     *     x={
-     *       "name": "getme"
-     *     },
-     *     @OA\Response(response="200", description="All good")
-     * )
-     */
-    public function getme($request, $response) {
-        return $response->write('Get me');
-    }
-}
-```
-
 ## Documentation
 * [Configuration](docs/Configuration.md)
-* [Annotation extensions](docs/AnnotationExtensions.md)
 
 ## License
 

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": {

docs/Configuration.md

@@ -4,14 +4,16 @@
 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`**
 ---
 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
+<?php
 
 use Radebatz\OpenApi\Routing\Adapters\LaravelRoutingAdapter;
 use Radebatz\OpenApi\Routing\OpenApiRouter;
@@ -57,7 +62,7 @@ use Symfony\Component\Cache\Simple\ArrayCache;
 
 ## Adapter Configuration
 Each framework is different and that means that not all features are available in all adapters.
-Configuration keys are available as constants on the `RoutingAdapterInterface` interface.
+Adapter configuration keys are available as constants on the `RoutingAdapterInterface` interface.
 
 Right now these options are available:
 
@@ -86,6 +91,7 @@ Available for:
 ### Example use
 
 ```php
+<?php
 
 use Radebatz\OpenApi\Routing\Adapters\LaravelRoutingAdapter;
 use Radebatz\OpenApi\Routing\OpenApiRouter;