<?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()];

    }

}

        $action = Utils::getRouteClassAndMethodNames($route->getAction());

        list($class, $method) = Utils::getRouteClassAndMethodNames($action);

namespace Mpociot\ApiDoc\Strategies\Responses;

use Mpociot\Reflection\DocBlock;

use Mpociot\ApiDoc\Strategies\Strategy;

use Mpociot\ApiDoc\Tools\RouteDocBlocker;

class UseResponseFileTag extends Strategy

     * @param \ReflectionClass $controller

     * @param \ReflectionMethod $method

     * @param array $routeRules

     * @param array $context

     *

     * @throws \Exception

    public function __invoke(Route $route, \ReflectionClass $controller, \ReflectionMethod $method, array $routeRules, array $context = [])

        $docBlocks = RouteDocBlocker::getDocBlocksFromRoute($route);

        /** @var DocBlock $methodDocBlock */

        $methodDocBlock = $docBlocks['method'];

        return $this->getFileResponses($methodDocBlock->getTags());

        $responses = array_map(function (Tag $responseFileTag) {

            return [json_encode($merged), (int) $status];

        // Convert responses to [200 => 'response', 401 => 'response']

        return collect($responses)->pluck('0', '1')->toArray();

use Illuminate\Support\Arr;

        list($controllerName, $methodName) = Utils::getRouteClassAndMethodNames($route->getAction());

        $controller = new ReflectionClass($controllerName);

        $method = $controller->getMethod($methodName);

        $metadata = $this->fetchMetadata($controller, $method, $route, $rulesToApply, $parsedRoute);

        $parsedRoute['metadata'] = $metadata;

        $bodyParameters = $this->fetchBodyParameters($controller, $method, $route, $rulesToApply, $parsedRoute);

        $parsedRoute['bodyParameters'] = $bodyParameters;

        $parsedRoute['cleanBodyParameters'] = $this->cleanParams($bodyParameters);

        $queryParameters = $this->fetchQueryParameters($controller, $method, $route, $rulesToApply, $parsedRoute);

        $parsedRoute['queryParameters'] = $queryParameters;

        $parsedRoute['cleanQueryParameters'] = $this->cleanParams($queryParameters);

        $responses = $this->fetchResponses($controller, $method, $route, $rulesToApply, $parsedRoute);

        $parsedRoute['response'] = $responses;

        $parsedRoute['showresponse'] = ! empty($responses);

        $parsedRoute['headers'] = $rulesToApply['headers'] ?? [];

        $parsedRoute += $metadata;

        return $parsedRoute;

    protected function fetchMetadata(ReflectionClass $controller, ReflectionMethod $method, Route $route, array $rulesToApply, array $context = [])

        $context['metadata'] = [

            'groupName' => $this->config->get('default_group', ''),

            'groupDescription' => '',

            'title' => '',

            'description' => '',

            'authenticated' => false,

        ];

        return $this->iterateThroughStrategies('metadata', $context, [$route, $controller, $method, $rulesToApply]);

    protected function fetchBodyParameters(ReflectionClass $controller, ReflectionMethod $method, Route $route, array $rulesToApply, array $context = [])

        return $this->iterateThroughStrategies('bodyParameters', $context, [$route, $controller, $method, $rulesToApply]);

    protected function fetchQueryParameters(ReflectionClass $controller, ReflectionMethod $method, Route $route, array $rulesToApply, array $context = [])

        return $this->iterateThroughStrategies('queryParameters', $context, [$route, $controller, $method, $rulesToApply]);

    protected function fetchResponses(ReflectionClass $controller, ReflectionMethod $method, Route $route, array $rulesToApply, array $context = [])

        $responses = $this->iterateThroughStrategies('responses', $context, [$route, $controller, $method, $rulesToApply]);

        if (count($responses)) {

            return collect($responses)->map(function (string $response, int $status) {

                return [

                    'status' => $status ?: 200,

                    'content' => $response,

                ];

            })->values()->toArray();

        }

        return null;

    protected function iterateThroughStrategies(string $stage, array $context, array $arguments)

        $strategies = $this->config->get("strategies.$stage", []);

        $context[$stage] = $context[$stage] ?? [];

        foreach ($strategies as $strategyClass) {

            $strategy = new $strategyClass($stage, $this->config);

            $arguments[] = $context;

            $results = $strategy(...$arguments);

            if (! is_null($results)) {

                foreach ($results as $index => $item) {

                    // Using a for loop rather than array_merge or +=

                    // so it does not renumber numeric keys

                    // and also allows values to be overwritten

                    // Don't allow overwriting if an empty value is trying to replace a set one

                    if (! in_array($context[$stage], [null, ''], true) && in_array($item, [null, ''], true)) {

                        continue;

                    } else {

                        $context[$stage][$index] = $item;

        return $context[$stage];

     * Create samples at index 0 for array parameters.

     * Also filter out parameters which were excluded from having examples.

     * @param array $params

     * @return array

    protected function cleanParams(array $params)

        $values = [];

        // Remove params which have no examples.

        $params = array_filter($params, function ($details) {

            return ! is_null($details['value']);

        });

        foreach ($params as $paramName => $details) {

            $this->generateConcreteSampleForArrayKeys(

                $paramName, $details['value'], $values

            );

        }

        return $values;

     * For each array notation parameter (eg user.*, item.*.name, object.*.*, user[])

     * generate concrete sample (user.0, item.0.name, object.0.0, user.0) with example as value.

     * @param string $paramName

     * @param mixed $paramExample

     * @param array $values The array that holds the result

     * @return void

    protected function generateConcreteSampleForArrayKeys($paramName, $paramExample, array &$values = [])

        if (Str::contains($paramName, '[')) {

            // Replace usages of [] with dot notation

            $paramName = str_replace(['][', '[', ']', '..'], ['.', '.', '', '.*.'], $paramName);

        // Then generate a sample item for the dot notation

        Arr::set($values, str_replace('.*', '.0', $paramName), $paramExample);

<?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;

    }

}

<?php

namespace Mpociot\ApiDoc\Tools;

use ReflectionClass;

use Illuminate\Routing\Route;

use Mpociot\Reflection\DocBlock;

class RouteDocBlocker

{

    protected static $docBlocks = [];

    /**

     * @param Route $route

     *

     * @throws \ReflectionException

     *

     * @return array<string, DocBlock> Method and class docblocks

     */

    public static function getDocBlocksFromRoute(Route $route): array

    {

        list($className, $methodName) = Utils::getRouteClassAndMethodNames($route);

        $docBlocks = self::getCachedDocBlock($route, $className, $methodName);

        if ($docBlocks) {

            return $docBlocks;

        }

        $class = new ReflectionClass($className);

        if (! $class->hasMethod($methodName)) {

            throw new \Exception("Error while fetching docblock for route: Class $className does not contain method $methodName");

        }

        $docBlocks = [

            'method' => new DocBlock($class->getMethod($methodName)->getDocComment() ?: ''),

            'class' => new DocBlock($class->getDocComment() ?: ''),

        ];

        self::cacheDocBlocks($route, $className, $methodName, $docBlocks);

        return $docBlocks;

    }

    protected static function getCachedDocBlock(Route $route, string $className, string $methodName)

    {

        $routeId = self::getRouteCacheId($route, $className, $methodName);

        return self::$docBlocks[$routeId] ?? null;

    }

    protected static function cacheDocBlocks(Route $route, string $className, string $methodName, array $docBlocks)

    {

        $routeId = self::getRouteCacheId($route, $className, $methodName);

        self::$docBlocks[$routeId] = $docBlocks;

    }

    private static function getRouteCacheId(Route $route, string $className, string $methodName): string

    {

        return $route->uri()

            .':'

            .implode(array_diff($route->methods(), ['HEAD']))

            .$className

            .$methodName;

    }

}

namespace Mpociot\ApiDoc\Strategies\Responses;

use Mpociot\ApiDoc\Strategies\Strategy;

class ResponseCalls extends Strategy

     * @param \ReflectionClass $controller

     * @param \ReflectionMethod $method

     * @param array $routeRules

     * @param array $context

    public function __invoke(Route $route, \ReflectionClass $controller, \ReflectionMethod $method, array $routeRules, array $context = [])

        $rulesToApply = $routeRules['response_calls'] ?? [];

        if (! $this->shouldMakeApiCall($route, $rulesToApply, $context)) {

        // Mix in parsed parameters with manually specified parameters.

        $bodyParameters = array_merge($context['cleanBodyParameters'], $rulesToApply['body'] ?? []);

        $queryParameters = array_merge($context['cleanQueryParameters'], $rulesToApply['query'] ?? []);

        $request = $this->prepareRequest($route, $rulesToApply, $bodyParameters, $queryParameters);

            $response = [200 => $this->makeApiCall($request)->getContent()];

    private function shouldMakeApiCall(Route $route, array $rulesToApply, array $context): bool

        if (! empty($context['responses'])) {

            // Don't attempt a response call if there are already responses

            return false;

        }

     * @param array|Route $routeOrAction

    public static function getRouteClassAndMethodNames($routeOrAction)

        $action = $routeOrAction instanceof Route ? $routeOrAction->getAction() : $routeOrAction;

<?php

namespace Mpociot\ApiDoc\Tools\Traits;

use Mpociot\Reflection\DocBlock\Tag;

trait DocBlockParamHelpers

{

    use ParamHelpers;

    /**

     * Allows users to specify that we shouldn't generate an example for the parameter

     * by writing 'No-example'.

     *

     * @param Tag $tag

     *

     * @return bool Whether no example should be generated

     */

    protected function shouldExcludeExample(Tag $tag)

    {

        return strpos($tag->getContent(), ' No-example') !== false;

    }

    /**

     * Allows users to specify an example for the parameter by writing 'Example: the-example',

     * to be used in example requests and response calls.

     *

     * @param string $description

     * @param string $type The type of the parameter. Used to cast the example provided, if any.

     *

     * @return array The description and included example.

     */

    protected function parseParamDescription(string $description, string $type)

    {

        $example = null;

        if (preg_match('/(.*)\s+Example:\s*(.*)\s*/', $description, $content)) {

            $description = $content[1];

            // examples are parsed as strings by default, we need to cast them properly

            $example = $this->castToType($content[2], $type);

        }

        return [$description, $example];

    }

}

use Faker\Factory;

    protected function generateDummyValue(string $type)

    {

        $faker = Factory::create();

        if ($this->config->get('faker_seed')) {

            $faker->seed($this->config->get('faker_seed'));

        }

        $fakeFactories = [

            'integer' => function () use ($faker) {

                return $faker->numberBetween(1, 20);

            },

            'number' => function () use ($faker) {

                return $faker->randomFloat();

            },

            'float' => function () use ($faker) {

                return $faker->randomFloat();

            },

            'boolean' => function () use ($faker) {

                return $faker->boolean();

            },

            'string' => function () use ($faker) {

                return $faker->word;

            },

            'array' => function () {

                return [];

            },

            'object' => function () {

                return new \stdClass;