Merge pull request mpociot#570 from mpociot/plugin-arch

Switch to plugin architecture

Author: shalvah

config/apidoc.php

@@ -179,6 +179,24 @@
         ],
     ],
 
+    'strategies' => [
+        'metadata' => [
+            \Mpociot\ApiDoc\Strategies\Metadata\GetFromDocBlocks::class,
+        ],
+        'bodyParameters' => [
+            \Mpociot\ApiDoc\Strategies\BodyParameters\GetFromBodyParamTag::class,
+        ],
+        'queryParameters' => [
+            \Mpociot\ApiDoc\Strategies\QueryParameters\GetFromQueryParamTag::class,
+        ],
+        'responses' => [
+            \Mpociot\ApiDoc\Strategies\Responses\UseResponseTag::class,
+            \Mpociot\ApiDoc\Strategies\Responses\UseResponseFileTag::class,
+            \Mpociot\ApiDoc\Strategies\Responses\UseTransformerTags::class,
+            \Mpociot\ApiDoc\Strategies\Responses\ResponseCalls::class,
+        ],
+    ],
+
     /*
      * Custom logo path. The logo will be copied from this location
      * during the generate process. Set this to false to use the default logo.

docs/index.md

@@ -9,6 +9,7 @@ Automatically generate your API documentation from your existing Laravel/Lumen/[
 * [Configuration](config.md)
 * [Generating Documentation](generating-documentation.md)
 * [Documenting Your API](documenting.md)
+* [Extending functionality with plugins](plugins.md)
 * [Internal Architecture](architecture.md)
 
 ## Installation

docs/plugins.md

@@ -0,0 +1,140 @@
+# Extending functionality with plugins
+You can use plugins to alter how the Generator fetches data about your routes. For instance, suppose all your routes have a body parameter `organizationId`, and you don't want to annotate this with `@queryParam` on each method. You can create a plugin that adds this to all your body parameters. Let's see how to do this.
+
+## The stages of route processing
+Route processing is performed in four stages:
+- metadata (this covers route `title`, route `description`, route `groupName`, route `groupDescription`, and authentication status (`authenticated`))
+- bodyParameters
+- queryParameters
+- responses
+
+For each stage, the Generator attempts one or more configured strategies to fetch data. The Generator will call of the strategies configured, progressively combining their results together before to produce the final output of that stage.
+
+## Strategies
+To create a strategy, create a class that extends `\Mpociot\ApiDoc\Strategies\Strategy`.
+
+The `__invoke` method of the strategy is where you perform your actions and return data. It receives the following arguments:
+- the route (instance of `\Illuminate\Routing\Route`)
+- the controller class handling the route (`\ReflectionClass`)
+- the controller method (`\ReflectionMethod $method`)
+ - the rules specified in the apidoc.php config file for the group this route belongs to, under the `apply` section (array)
+ - the context. This contains all data for the route that has been parsed thus far in the previous stages. This means, by the `responses` stage, the context will contain the following keys: `metadata`, `bodyParameters` and `queryParameters`.
+ 
+ Here's what your strategy in our example would look like:
+ 
+ ```php
+<?php
+
+use Illuminate\Routing\Route;
+use Mpociot\ApiDoc\Strategies\Strategy;
+
+class AddOrganizationIdBodyParameter extends Strategy
+{
+    public function __invoke(Route $route, \ReflectionClass $controller, \ReflectionMethod $method, array $routeRules, array $context = [])
+    {
+        return [
+            'organizationId' => [
+                'type' => 'integer',
+                'description' => 'The ID of the organization', 
+                'required' => true, 
+                'value' => 2,
+            ]
+        ];
+    }
+}
+```
+
+The last thing to do is to register the strategy. Strategies are registered in a `strategies` key in the `apidoc.php` file. Here's what the file looks like by default:
+
+```php
+...
+    'strategies' => [
+        'metadata' => [
+            \Mpociot\ApiDoc\Strategies\Metadata\GetFromDocBlocks::class,
+        ],
+        'bodyParameters' => [
+            \Mpociot\ApiDoc\Strategies\BodyParameters\GetFromBodyParamTag::class,
+        ],
+        'queryParameters' => [
+            \Mpociot\ApiDoc\Strategies\QueryParameters\GetFromQueryParamTag::class,
+        ],
+        'responses' => [
+            \Mpociot\ApiDoc\Strategies\Responses\UseResponseTag::class,
+            \Mpociot\ApiDoc\Strategies\Responses\UseResponseFileTag::class,
+            \Mpociot\ApiDoc\Strategies\Responses\UseTransformerTags::class,
+            \Mpociot\ApiDoc\Strategies\Responses\ResponseCalls::class,
+        ],
+    ],
+...
+```
+
+You can add, replace or remove strategies from here. In our case, we're adding our bodyParameter strategy:
+
+```php
+
+        'bodyParameters' => [
+            \Mpociot\ApiDoc\Strategies\BodyParameters\GetFromBodyParamTag::class,
+            AddOrganizationIdBodyParameter::class,
+        ],
+```
+
+And we're done. Now, when we run `php artisan docs:generate`, all our routes will have this bodyParameter added.
+
+
+We could go further and modify our strategy so it doesn't add this parameter if the route is a GET route or is authenticated:
+
+```php
+public function __invoke(Route $route, \ReflectionClass $controller, \ReflectionMethod $method, array $routeRules, array $context = [])
+{
+    if (in_array('GET', $route->methods()) {
+        return null;
+    }
+
+    if ($context['metadata']['authenticated']) {
+        return null;
+    }
+
+    return [
+        'organizationId' => [
+            'type' => 'integer',
+            'description' => 'The ID of the organization', 
+            'required' => true, 
+            'value' => 2,
+        ]
+    ];
+}
+```
+
+The strategy class also has access to the current apidoc configuration via its `config` property. For instance, you can retrieve the default group with `$this->config->get('default_group')`.
+
+Yopu are also provided with the instance pproperty `stage`, which is set to the name of the currently executing stage.
+
+
+## Utilities
+You have access to a number of tools when developing strategies. They include:
+
+- The `RouteDocBlocker` class (in the `\Mpociot\ApiDoc\Tools` namespace) has a single public static method, `getDocBlocksFromRoute(Route $route)`. It allows you to retrieve the docblocks for a given route. It returns an array of with two keys: `method` and `class` containing the docblocks for the method and controller handling the route respectively. Both are instances of `\Mpociot\Reflection\DocBlock`.
+
+- The `ParamsHelper` trait (in the `\Mpociot\ApiDoc\Tools` namespace) can be included in your strategies. It contains a number of useful methods for working with parameters, including type casting and generating dummy values.
+
+## API
+Each strategy class must implement the __invoke method with the parameters as described above. This method must return the needed data for the intended stage, or `null` to indicate failure.
+- In the `metadata` stage, strategies should return an array. These are the expected keys (you may omit some, or all):
+
+```
+'groupName'
+'groupDescription'
+'title'
+'description'
+'authenticated' // boolean
+```
+
+- In the `bodyParameters` and `queryParameters` stages, you can return an array with arbitrary keys. These keys will serve as the names of your parameters. Array keys can be indicated with Laravel's dot notation. The value of each key should be an array with the following keys:
+
+```
+'type', // Only used in bodyParameters
+'description', 
+'required', // boolean
+'value', // An example value for the parameter
+```
+- In the `responses` stage, your strategy should return an array containing the responses for different status codes. Each key in the array should be a HTTP status code, and each value should be a string containing the response.

src/Commands/GenerateDocumentation.php

@@ -247,7 +247,7 @@ private function processRoutes(Generator $generator, array $routes)
      */
     private function isValidRoute(Route $route)
     {
-        $action = Utils::getRouteActionUses($route->getAction());
+        $action = Utils::getRouteClassAndMethodNames($route->getAction());
         if (is_array($action)) {
             $action = implode('@', $action);
         }
@@ -264,7 +264,7 @@ private function isValidRoute(Route $route)
      */
     private function isRouteVisibleForDocumentation(array $action)
     {
-        list($class, $method) = Utils::getRouteActionUses($action);
+        list($class, $method) = Utils::getRouteClassAndMethodNames($action);
         $reflection = new ReflectionClass($class);
 
         if (! $reflection->hasMethod($method)) {

src/Strategies/BodyParameters/GetFromBodyParamTag.php

@@ -0,0 +1,90 @@
+<?php
+
+namespace Mpociot\ApiDoc\Strategies\BodyParameters;
+
+use ReflectionClass;
+use ReflectionMethod;
+use Illuminate\Routing\Route;
+use Mpociot\Reflection\DocBlock;
+use Mpociot\Reflection\DocBlock\Tag;
+use Mpociot\ApiDoc\Strategies\Strategy;
+use Mpociot\ApiDoc\Tools\RouteDocBlocker;
+use Dingo\Api\Http\FormRequest as DingoFormRequest;
+use Mpociot\ApiDoc\Tools\Traits\DocBlockParamHelpers;
+use Illuminate\Foundation\Http\FormRequest as LaravelFormRequest;
+
+class GetFromBodyParamTag extends Strategy
+{
+    use DocBlockParamHelpers;
+
+    public function __invoke(Route $route, ReflectionClass $controller, ReflectionMethod $method, array $routeRules, array $context = [])
+    {
+        foreach ($method->getParameters() as $param) {
+            $paramType = $param->getType();
+            if ($paramType === null) {
+                continue;
+            }
+
+            $parameterClassName = version_compare(phpversion(), '7.1.0', '<')
+                ? $paramType->__toString()
+                : $paramType->getName();
+
+            try {
+                $parameterClass = new ReflectionClass($parameterClassName);
+            } catch (\ReflectionException $e) {
+                continue;
+            }
+
+            // If there's a FormRequest, we check there for @bodyParam tags.
+            if (class_exists(LaravelFormRequest::class) && $parameterClass->isSubclassOf(LaravelFormRequest::class)
+                || class_exists(DingoFormRequest::class) && $parameterClass->isSubclassOf(DingoFormRequest::class)) {
+                $formRequestDocBlock = new DocBlock($parameterClass->getDocComment());
+                $bodyParametersFromDocBlock = $this->getBodyParametersFromDocBlock($formRequestDocBlock->getTags());
+
+                if (count($bodyParametersFromDocBlock)) {
+                    return $bodyParametersFromDocBlock;
+                }
+            }
+        }
+
+        $methodDocBlock = RouteDocBlocker::getDocBlocksFromRoute($route)['method'];
+
+        return $this->getBodyParametersFromDocBlock($methodDocBlock->getTags());
+    }
+
+    private function getBodyParametersFromDocBlock($tags)
+    {
+        $parameters = collect($tags)
+            ->filter(function ($tag) {
+                return $tag instanceof Tag && $tag->getName() === 'bodyParam';
+            })
+            ->mapWithKeys(function ($tag) {
+                preg_match('/(.+?)\s+(.+?)\s+(required\s+)?(.*)/', $tag->getContent(), $content);
+                $content = preg_replace('/\s?No-example.?/', '', $content);
+                if (empty($content)) {
+                    // this means only name and type were supplied
+                    list($name, $type) = preg_split('/\s+/', $tag->getContent());
+                    $required = false;
+                    $description = '';
+                } else {
+                    list($_, $name, $type, $required, $description) = $content;
+                    $description = trim($description);
+                    if ($description == 'required' && empty(trim($required))) {
+                        $required = $description;
+                        $description = '';
+                    }
+                    $required = trim($required) == 'required' ? true : false;
+                }
+
+                $type = $this->normalizeParameterType($type);
+                list($description, $example) = $this->parseParamDescription($description, $type);
+                $value = is_null($example) && ! $this->shouldExcludeExample($tag)
+                    ? $this->generateDummyValue($type)
+                    : $example;
+
+                return [$name => compact('type', 'description', 'required', 'value')];
+            })->toArray();
+
+        return $parameters;
+    }
+}

src/Strategies/Metadata/GetFromDocBlocks.php

@@ -0,0 +1,100 @@
+<?php
+
+namespace Mpociot\ApiDoc\Strategies\Metadata;
+
+use ReflectionClass;
+use ReflectionMethod;
+use Illuminate\Routing\Route;
+use Mpociot\Reflection\DocBlock;
+use Mpociot\Reflection\DocBlock\Tag;
+use Mpociot\ApiDoc\Strategies\Strategy;
+use Mpociot\ApiDoc\Tools\RouteDocBlocker;
+
+class GetFromDocBlocks extends Strategy
+{
+    public function __invoke(Route $route, ReflectionClass $controller, ReflectionMethod $method, array $routeRules, array $context = [])
+    {
+        $docBlocks = RouteDocBlocker::getDocBlocksFromRoute($route);
+        /** @var DocBlock $methodDocBlock */
+        $methodDocBlock = $docBlocks['method'];
+
+        list($routeGroupName, $routeGroupDescription, $routeTitle) = $this->getRouteGroupDescriptionAndTitle($methodDocBlock, $docBlocks['class']);
+
+        return [
+                'groupName' => $routeGroupName,
+                'groupDescription' => $routeGroupDescription,
+                'title' => $routeTitle ?: $methodDocBlock->getShortDescription(),
+                'description' => $methodDocBlock->getLongDescription()->getContents(),
+                'authenticated' => $this->getAuthStatusFromDocBlock($methodDocBlock->getTags()),
+        ];
+    }
+
+    /**
+     * @param array $tags Tags in the method doc block
+     *
+     * @return bool
+     */
+    protected function getAuthStatusFromDocBlock(array $tags)
+    {
+        $authTag = collect($tags)
+            ->first(function ($tag) {
+                return $tag instanceof Tag && strtolower($tag->getName()) === 'authenticated';
+            });
+
+        return (bool) $authTag;
+    }
+
+    /**
+     * @param DocBlock $methodDocBlock
+     * @param DocBlock $controllerDocBlock
+     *
+     * @return array The route group name, the group description, ad the route title
+     */
+    protected function getRouteGroupDescriptionAndTitle(DocBlock $methodDocBlock, DocBlock $controllerDocBlock)
+    {
+        // @group tag on the method overrides that on the controller
+        if (! empty($methodDocBlock->getTags())) {
+            foreach ($methodDocBlock->getTags() as $tag) {
+                if ($tag->getName() === 'group') {
+                    $routeGroupParts = explode("\n", trim($tag->getContent()));
+                    $routeGroupName = array_shift($routeGroupParts);
+                    $routeGroupDescription = trim(implode("\n", $routeGroupParts));
+
+                    // If the route has no title (the methodDocBlock's "short description"),
+                    // we'll assume the routeGroupDescription is actually the title
+                    // Something like this:
+                    // /**
+                    //   * Fetch cars. <-- This is route title.
+                    //   * @group Cars <-- This is group name.
+                    //   * APIs for cars. <-- This is group description (not required).
+                    //   **/
+                    // VS
+                    // /**
+                    //   * @group Cars <-- This is group name.
+                    //   * Fetch cars. <-- This is route title, NOT group description.
+                    //   **/
+
+                    // BTW, this is a spaghetti way of doing this.
+                    // It shall be refactored soon. Deus vult!💪
+                    if (empty($methodDocBlock->getShortDescription())) {
+                        return [$routeGroupName, '', $routeGroupDescription];
+                    }
+
+                    return [$routeGroupName, $routeGroupDescription, $methodDocBlock->getShortDescription()];
+                }
+            }
+        }
+
+        foreach ($controllerDocBlock->getTags() as $tag) {
+            if ($tag->getName() === 'group') {
+                $routeGroupParts = explode("\n", trim($tag->getContent()));
+                $routeGroupName = array_shift($routeGroupParts);
+                $routeGroupDescription = implode("\n", $routeGroupParts);
+
+                return [$routeGroupName, $routeGroupDescription, $methodDocBlock->getShortDescription()];
+            }
+        }
+
+        return [$this->config->get('default_group'), '', $methodDocBlock->getShortDescription()];
+    }
+}