Merge pull request #4 from FandaOG/vyuldashev-master

Vyuldashev master

Author: qwasyx0

.github/workflows/tests.yml

@@ -13,10 +13,9 @@ jobs:
     strategy:
       fail-fast: true
       matrix:
-        php: [8.0]
-        stability: [prefer-lowest, prefer-stable]
+        php: [8.0, 8.1]
 
-    name: PHP ${{ matrix.php }} - ${{ matrix.stability }}
+    name: PHP ${{ matrix.php }}
 
     steps:
       - name: Checkout code
@@ -30,7 +29,7 @@ jobs:
           coverage: none
 
       - name: Install dependencies
-        run: composer update --${{ matrix.stability }} --prefer-dist --no-interaction --no-progress
+        run: composer update --prefer-dist --no-interaction --no-progress
 
       - name: Execute tests
         run: vendor/bin/phpunit --verbose

composer.json

@@ -28,7 +28,7 @@
     },
     "require-dev": {
         "orchestra/testbench": "^5.3|^6.0|^7.0",
-        "phpunit/phpunit": "^9.4"
+        "phpunit/phpunit": "^9.5.13"
     },
     "autoload": {
         "psr-4": {

config/openapi.php

@@ -10,11 +10,14 @@
                 'title' => config('app.name'),
                 'description' => null,
                 'version' => '1.0.0',
+                'contact' => [],
             ],
 
             'servers' => [
                 [
                     'url' => env('APP_URL'),
+                    'description' => null,
+                    'variables' => [],
                 ],
             ],
 
@@ -43,6 +46,9 @@
                 'paths' => [
                     //
                 ],
+                'components' => [
+                    //
+                ],
             ],
 
         ],

docs/.vuepress/config.js

@@ -26,6 +26,7 @@ module.exports = {
       '/schemas',
       '/collections',
       '/middlewares',
+      '/security'
     ],
     displayAllHeaders: true,
     sidebarDepth: 2,

docs/middlewares.md

@@ -1,2 +1,18 @@
 # Middlewares
 
+Middlewares are an optional bit of logic to transform the given data at various lifecycle points.
+
+### Path
+
+To add a path middleware create a class that implements `\Vyuldashev\LaravelOpenApi\Contracts\PathMiddleware` then register it by referencing it in the  `openapi.collections.default.middlewares.paths` config array like `MyPathMiddleware::class`
+
+Available lifecycle points are:
+ - `before` - after collecting all `RouteInformation` but before processing them.
+ - `after` - after the `PathItem` has been built.
+
+### Component
+
+To add a path middleware create a class that implements `\Vyuldashev\LaravelOpenApi\Contracts\ComponentMiddleware` then register it by referencing it in the  `openapi.collections.default.middlewares.components` config array like `MyComponentMiddleware::class`
+
+Available lifecycle points are:
+- `after` - after the `Components` has been built.

docs/paths/operations.md

@@ -39,6 +39,10 @@ The following definition will be generated:
 }
 ```
 
+## Security
+
+See [Security](../security.md#operation-level-example)
+
 ## Tags
 
 Tags can be used for logical grouping of operations by resources or any other qualifier.

docs/security.md

@@ -0,0 +1,40 @@
+# Security
+
+```bash
+php artisan openapi:make-security-scheme BearerToken
+```
+
+After you generate a security scheme, it will be declared in the `securitySchemes` section, you can apply it to the whole API or individual operations by adding the security section on the root level or operation level, respectively. When used on the root level, security applies the specified security schemes globally to all API operations, unless overridden on the operation level.
+
+## Root level example
+
+`config/openapi.php`:
+
+```php
+
+'security' => [
+  GoldSpecDigital\ObjectOrientedOAS\Objects\SecurityRequirement::create()->securityScheme('BearerToken'),
+],
+
+```
+
+## Operation level example
+
+```php
+use Vyuldashev\LaravelOpenApi\Attributes as OpenApi;
+
+#[OpenApi\PathItem]
+class UserController extends Controller
+{
+    /**
+     * Create new user.
+     *
+     * Creates new user or returns already existing user by email.
+     */
+     #[OpenApi\Operation(security: 'BearerToken')]
+    public function store(Request $request)
+    {
+        //
+    }
+}
+```

examples/petstore/OpenApi/Schemas/PetSchema.php

@@ -12,6 +12,7 @@ class PetSchema extends SchemaFactory implements Reusable
 {
     /**
      * @return Schema
+     *
      * @throws InvalidArgumentException
      */
     public function build(): SchemaContract

src/Attributes/Operation.php

@@ -19,10 +19,11 @@ class Operation
     public ?string $method;
 
     /**
-     * @param string|null $id
-     * @param array $tags
-     * @param \Vyuldashev\LaravelOpenApi\Factories\SecuritySchemeFactory|string|null $security
-     * @param string|null $method
+     * @param  string|null  $id
+     * @param  array  $tags
+     * @param  \Vyuldashev\LaravelOpenApi\Factories\SecuritySchemeFactory|string|null  $security
+     * @param  string|null  $method
+     *
      * @throws InvalidArgumentException
      */
     public function __construct(string $id = null, array $tags = [], string $security = null, string $method = null)
@@ -31,14 +32,21 @@ public function __construct(string $id = null, array $tags = [], string $securit
         $this->tags = $tags;
         $this->method = $method;
 
+        if ($security === '') {
+            //user wants to turn off security on this operation
+            $this->security = $security;
+
+            return;
+        }
+
         if ($security) {
-            $this->security = class_exists($security) ? $security : app()->getNamespace() . 'OpenApi\\SecuritySchemes\\' . $security . 'SecurityScheme';
+            $this->security = class_exists($security) ? $security : app()->getNamespace().'OpenApi\\SecuritySchemes\\'.$security;
 
-            if (!is_a($this->security, SecuritySchemeFactory::class, true)) {
+            if (! is_a($this->security, SecuritySchemeFactory::class, true)) {
                 throw new InvalidArgumentException(
-                    sprintf('Security class is either not declared or is not an instance of [%s]', SecuritySchemeFactory::class)
+                    sprintf('Security class is either not declared or is not an instance of %s', SecuritySchemeFactory::class)
                 );
             }
         }
     }
-}
+}

src/Builders/Components/Builder.php

@@ -20,21 +20,21 @@ public function __construct(array $directories)
     protected function getAllClasses(string $collection): Collection
     {
         return collect($this->directories)
-            ->map(function(string $directory) {
+            ->map(function (string $directory) {
                 $map = ClassMapGenerator::createMap($directory);
 
                 return array_keys($map);
             })
             ->flatten()
-            ->filter(function(string $class) use($collection) {
+            ->filter(function (string $class) use ($collection) {
                 $reflectionClass = new ReflectionClass($class);
                 $collectionAttributes = $reflectionClass->getAttributes(CollectionAttribute::class);
 
-                if(count($collectionAttributes) === 0 && $collection === Generator::COLLECTION_DEFAULT) {
+                if (count($collectionAttributes) === 0 && $collection === Generator::COLLECTION_DEFAULT) {
                     return true;
                 }
 
-                if(count($collectionAttributes) === 0) {
+                if (count($collectionAttributes) === 0) {
                     return false;
                 }