added scope requirement to operation object

Author: mtrajano

src/Generator.php

@@ -5,11 +5,13 @@
 use Illuminate\Foundation\Http\FormRequest;
 use Illuminate\Routing\Route;
 use Illuminate\Support\Str;
+use Illuminate\Support\Arr;
 use phpDocumentor\Reflection\DocBlockFactory;
 use ReflectionMethod;
 
 class Generator
 {
+    const SECURITY_DEFINITION_NAME = 'OAuth2';
     const OAUTH_TOKEN_PATH = '/oauth/token';
     const OAUTH_AUTHORIZE_PATH = '/oauth/authorize';
 
@@ -20,18 +22,27 @@ class Generator
     protected $originalUri;
     protected $method;
     protected $action;
+    protected $middleware;
+    protected $docParser;
+    protected $hasSecurityDefinitions;
 
     public function __construct($config, $routeFilter = null)
     {
         $this->config = $config;
         $this->routeFilter = $routeFilter;
         $this->docParser = DocBlockFactory::createInstance();
+        $this->hasSecurityDefinitions = false;
     }
 
     public function generate()
     {
         $this->docs = $this->getBaseInfo();
 
+        if ($this->config['parseSecurity'] && $this->hasOauthRoutes()) {
+            $this->docs['securityDefinitions'] = $this->generateSecurityDefinitions();
+            $this->hasSecurityDefinitions = true;
+        }
+
         foreach ($this->getAppRoutes() as $route) {
             $this->originalUri = $uri = $this->getRouteUri($route);
             $this->uri = strip_optional_char($uri);
@@ -40,11 +51,11 @@ public function generate()
                 continue;
             }
 
-            if ($this->config['parseSecurity'] && $this->isOauthRoute()) {
-                $this->docs['securityDefinitions'] = $this->generateSecurityDefinitions();
-            }
+            $middleware = isset($route->getAction()['middleware']) ? $route->getAction()['middleware'] : [];
 
             $this->action = $route->getAction()['uses'];
+            $this->middleware = $this->formatMiddleware($middleware);
+
             $methods = $route->methods();
 
             if (!isset($this->docs['paths'][$this->uri])) {
@@ -118,22 +129,22 @@ protected function generateSecurityDefinitions()
         $this->validateAuthFlow($authFlow);
 
         $securityDefinition = [
-            'OAuth2' => [
+            self::SECURITY_DEFINITION_NAME => [
                 'type' => 'oauth2',
                 'flow' => $authFlow,
             ]
         ];
 
 
         if (in_array($authFlow, ['implicit', 'accessCode'])) {
-            $securityDefinition['OAuth2']['authorizationUrl'] = $this->getEndpoint(self::OAUTH_AUTHORIZE_PATH);
+            $securityDefinition[self::SECURITY_DEFINITION_NAME]['authorizationUrl'] = $this->getEndpoint(self::OAUTH_AUTHORIZE_PATH);
         }
 
         if (in_array($authFlow, ['password', 'application', 'accessCode'])) {
-            $securityDefinition['OAuth2']['tokenUrl'] = $this->getEndpoint(self::OAUTH_TOKEN_PATH);
+            $securityDefinition[self::SECURITY_DEFINITION_NAME]['tokenUrl'] = $this->getEndpoint(self::OAUTH_TOKEN_PATH);
         }
 
-        $securityDefinition['OAuth2']['scopes'] = $this->generateOauthScopes();
+        $securityDefinition[self::SECURITY_DEFINITION_NAME]['scopes'] = $this->generateOauthScopes();
 
         return $securityDefinition;
     }
@@ -157,6 +168,10 @@ protected function generatePath()
         ];
 
         $this->addActionParameters();
+
+        if ($this->hasSecurityDefinitions) {
+            $this->addActionScopes();
+        }
     }
 
     protected function addActionParameters()
@@ -176,6 +191,17 @@ protected function addActionParameters()
         }
     }
 
+    protected function addActionScopes()
+    {
+        foreach ($this->middleware as $middleware) {
+            if ($middleware['name'] === 'scope' || $middleware['name'] === 'scopes') {
+                $this->docs['paths'][$this->uri][$this->method]['security'] = [
+                    self::SECURITY_DEFINITION_NAME => $middleware['parameters']
+                ];
+            }
+        }
+    }
+
     protected function getFormRules()
     {
         if (!is_string($this->action)) {
@@ -237,9 +263,20 @@ private function isFilteredRoute()
         return !preg_match('/^' . preg_quote($this->routeFilter, '/') . '/', $this->uri);
     }
 
-    private function isOauthRoute()
+    /**
+     * Assumes routes have been created using Passport::routes()
+     */
+    private function hasOauthRoutes()
     {
-        return $this->uri === self::OAUTH_TOKEN_PATH || $this->uri === self::OAUTH_AUTHORIZE_PATH;
+        foreach ($this->getAppRoutes() as $route) {
+            $uri = $this->getRouteUri($route);
+
+            if ($uri === self::OAUTH_TOKEN_PATH || $uri === self::OAUTH_AUTHORIZE_PATH) {
+                return true;
+            }
+        }
+
+        return false;
     }
 
     private function getEndpoint(string $path)
@@ -264,4 +301,17 @@ private function validateAuthFlow(string $flow)
             throw new LaravelSwaggerException('Invalid OAuth flow passed');
         }
     }
+
+    private function formatMiddleware($middleware)
+    {
+        $middleware = Arr::wrap($middleware);
+
+        return array_map(function($mw) {
+            $tokens = explode(':', $mw, 2);
+            $name = $tokens[0];
+            $parameters = isset($tokens[1]) ? explode(',', $tokens[1]) : [];
+
+            return compact('name', 'parameters');
+        }, $middleware);
+    }
 }

tests/GeneratorTest.php

@@ -220,6 +220,15 @@ public function testRouteData($paths)
         $this->assertEquals('', $paths['/users/details']['get']['description']);
     }
 
+    /**
+     * @depends testHasPaths
+     */
+    public function testRouteScopes($paths)
+    {
+        $this->assertEquals(['user-read'], $paths['/users']['get']['security'][Generator::SECURITY_DEFINITION_NAME]);
+        $this->assertEquals(['user-write', 'user-read'], $paths['/users']['post']['security'][Generator::SECURITY_DEFINITION_NAME]);
+    }
+
     public function testOverwriteIgnoreMethods()
     {
         $docs = $this->getDocsWithNewConfig(['ignoredMethods' => []]);

tests/TestCase.php

@@ -14,13 +14,17 @@ protected function getPackageProviders($app)
 
     protected function getEnvironmentSetUp($app)
     {
-        $app['router']->get('/users', 'Mtrajano\\LaravelSwagger\\Tests\\Stubs\\Controllers\\UserController@index');
-        $app['router']->get('/users/{id}', 'Mtrajano\\LaravelSwagger\\Tests\\Stubs\\Controllers\\UserController@show');
-        $app['router']->post('/users', 'Mtrajano\\LaravelSwagger\\Tests\\Stubs\\Controllers\\UserController@store');
-        $app['router']->get('/users/details', 'Mtrajano\\LaravelSwagger\\Tests\\Stubs\\Controllers\\UserController@details');
-        $app['router']->get('/users/ping', function () {
-            return 'pong';
+        $app['router']->middleware(['some-middleware', 'scope:user-read'])->group(function() use($app) {
+            $app['router']->get('/users', 'Mtrajano\\LaravelSwagger\\Tests\\Stubs\\Controllers\\UserController@index');
+            $app['router']->get('/users/{id}', 'Mtrajano\\LaravelSwagger\\Tests\\Stubs\\Controllers\\UserController@show');
+            $app['router']->post('/users', 'Mtrajano\\LaravelSwagger\\Tests\\Stubs\\Controllers\\UserController@store')
+                ->middleware('scopes:user-write,user-read');
+            $app['router']->get('/users/details', 'Mtrajano\\LaravelSwagger\\Tests\\Stubs\\Controllers\\UserController@details');
+            $app['router']->get('/users/ping', function () {
+                return 'pong';
+            });
         });
+
         $app['router']->get('/api', 'Mtrajano\\LaravelSwagger\\Tests\\Stubs\\Controllers\\ApiController@index');
         $app['router']->put('/api/store', 'Mtrajano\\LaravelSwagger\\Tests\\Stubs\\Controllers\\ApiController@store');