GenerateDocumentation::writeMarkdown() - Code Metrics - Inspection of "Feature" - mpociot/laravel-apidoc-generator - Measure and Improve Code Quality continuously with Scrutinizer

Completed

Pull Request — master (#439)

unknown

created 2018-12-23 15:34 UTC

GenerateDocumentation::writeMarkdown() C

↳ Parent: GenerateDocumentation

Complexity

Conditions	14
Paths	96

Size

Total Lines

110

Duplication

Lines	0
Ratio	0 %

Importance

Changes

Metric	Value
dl	0
loc	110
rs	5.0133
c	0
b	0
f	0
cc	14
nc	96
nop	1

How to fix Long Method Complexity

<?php

namespace Mpociot\ApiDoc\Commands;

use ReflectionClass;
use ReflectionException;
use Illuminate\Routing\Route;
use Illuminate\Console\Command;
use Mpociot\Reflection\DocBlock;
use Illuminate\Support\Collection;
use Mpociot\ApiDoc\Tools\Generator;
use Mpociot\ApiDoc\Tools\RouteMatcher;
use Mpociot\Documentarian\Documentarian;
use Mpociot\ApiDoc\Postman\CollectionWriter;

class GenerateDocumentation extends Command
{
    /**
     * The name and signature of the console command.
     *
     * @var string
     */
    protected $signature = 'apidoc:generate
                            {--force : Force rewriting of existing routes}
                            {--only-tags= : Comma-separated list of tags to generate}
                            {--skip-tags= : Comma-separated list of tags to skip}
    ';

    /**
     * The console command description.
     *
     * @var string
     */
    protected $description = 'Generate your API documentation from existing Laravel routes.';

    private $routeMatcher;

    public function __construct(RouteMatcher $routeMatcher)
    {
        parent::__construct();
        $this->routeMatcher = $routeMatcher;
    }

    /**
     * Execute the console command.
     *
     * @return void
     */
    public function handle()
    {
        $usingDingoRouter = strtolower(config('apidoc.router')) == 'dingo';
        if ($usingDingoRouter) {
            $routes = $this->routeMatcher->getDingoRoutesToBeDocumented(config('apidoc.routes'));
        } else {
            $routes = $this->routeMatcher->getLaravelRoutesToBeDocumented(config('apidoc.routes'));
        }

        $generator = new Generator();
        $parsedRoutes = $this->processRoutes($generator, $routes);
        $parsedRoutes = collect($parsedRoutes)->groupBy('group')
            ->sortBy(static function ($group) {
                /* @var $group Collection */
                return $group->first()['group'];
            }, SORT_NATURAL);

        $this->writeMarkdown($parsedRoutes);
    }

    /**
     * @param  Collection $parsedRoutes
     *
     * @return void
     */
    private function writeMarkdown($parsedRoutes)
    {
        $outputPath = config('apidoc.output');
        $targetFile = $outputPath.DIRECTORY_SEPARATOR.'source'.DIRECTORY_SEPARATOR.'index.md';
        $compareFile = $outputPath.DIRECTORY_SEPARATOR.'source'.DIRECTORY_SEPARATOR.'.compare.md';
        $prependFile = $outputPath.DIRECTORY_SEPARATOR.'source'.DIRECTORY_SEPARATOR.'prepend.md';
        $appendFile = $outputPath.DIRECTORY_SEPARATOR.'source'.DIRECTORY_SEPARATOR.'append.md';

        $infoText = view('apidoc::partials.info')
            ->with('outputPath', ltrim($outputPath, 'public/'))
            ->with('showPostmanCollectionButton', config('apidoc.postman'));

        $parsedRouteOutput = $parsedRoutes->map(function ($routeGroup) {
            return $routeGroup->map(function ($route) {
                $route['output'] = (string) view('apidoc::partials.route')->with('route', $route)->render();

                return $route;
            });
        });

        $frontmatter = view('apidoc::partials.frontmatter');
        /*
         * In case the target file already exists, we should check if the documentation was modified
         * and skip the modified parts of the routes.
         */
        if (file_exists($targetFile) && file_exists($compareFile)) {
            $generatedDocumentation = file_get_contents($targetFile);
            $compareDocumentation = file_get_contents($compareFile);

            if (preg_match('/---(.*)---\\s<!-- START_INFO -->/is', $generatedDocumentation, $generatedFrontmatter)) {
                $frontmatter = trim($generatedFrontmatter[1], "\n");
            }

            $parsedRouteOutput->transform(function ($routeGroup) use ($generatedDocumentation, $compareDocumentation) {
                return $routeGroup->transform(function ($route) use ($generatedDocumentation, $compareDocumentation) {
                    if (preg_match('/<!-- START_'.$route['id'].' -->(.*)<!-- END_'.$route['id'].' -->/is', $generatedDocumentation, $existingRouteDoc)) {
                        $routeDocumentationChanged = (preg_match('/<!-- START_'.$route['id'].' -->(.*)<!-- END_'.$route['id'].' -->/is', $compareDocumentation, $lastDocWeGeneratedForThisRoute) && $lastDocWeGeneratedForThisRoute[1] !== $existingRouteDoc[1]);
                        if ($routeDocumentationChanged === false || $this->option('force')) {
                            if ($routeDocumentationChanged) {
                                $this->warn('Discarded manual changes for route ['.implode(',', $route['methods']).'] '.$route['uri']);
                            }
                        } else {
                            $this->warn('Skipping modified route ['.implode(',', $route['methods']).'] '.$route['uri']);
                            $route['modified_output'] = $existingRouteDoc[0];
                        }
                    }

                    return $route;
                });
            });
        }

        $prependFileContents = file_exists($prependFile)
            ? file_get_contents($prependFile)."\n" : '';
        $appendFileContents = file_exists($appendFile)
            ? "\n".file_get_contents($appendFile) : '';

        $documentarian = new Documentarian();

        $markdown = view('apidoc::documentarian')
            ->with('writeCompareFile', false)
            ->with('frontmatter', $frontmatter)
            ->with('infoText', $infoText)
            ->with('prependMd', $prependFileContents)
            ->with('appendMd', $appendFileContents)
            ->with('outputPath', config('apidoc.output'))
            ->with('showPostmanCollectionButton', config('apidoc.postman'))
            ->with('parsedRoutes', $parsedRouteOutput);

        if (! is_dir($outputPath)) {
            $documentarian->create($outputPath);
        }

        // Write output file
        file_put_contents($targetFile, $markdown);

        // Write comparable markdown file
        $compareMarkdown = view('apidoc::documentarian')
            ->with('writeCompareFile', true)
            ->with('frontmatter', $frontmatter)
            ->with('infoText', $infoText)
            ->with('prependMd', $prependFileContents)
            ->with('appendMd', $appendFileContents)
            ->with('outputPath', config('apidoc.output'))
            ->with('showPostmanCollectionButton', config('apidoc.postman'))
            ->with('parsedRoutes', $parsedRouteOutput);

        file_put_contents($compareFile, $compareMarkdown);

        $this->info('Wrote index.md to: '.$outputPath);

        $this->info('Generating API HTML code');

        $documentarian->generate($outputPath);

        $this->info('Wrote HTML documentation to: '.$outputPath.'/index.html');

        if (config('apidoc.postman')) {
            $this->info('Generating Postman collection');

            file_put_contents($outputPath.DIRECTORY_SEPARATOR.'collection.json', $this->generatePostmanCollection($parsedRoutes));
        }

        if ($logo = config('apidoc.logo')) {
            copy(
                $logo,
                $outputPath.DIRECTORY_SEPARATOR.'images'.DIRECTORY_SEPARATOR.'logo.png'
            );
        }
    }

    /**
     * @param Generator $generator
     * @param array $routes
     *
     * @return array
     */
    private function processRoutes(Generator $generator, array $routes)
    {
        $parsedRoutes = [];
        foreach ($routes as $routeItem) {
            $route = $routeItem['route'];
            /** @var Route $route */
            if ($this->isValidRoute($route) && $this->isRouteVisibleForDocumentation($route->getAction()['uses'])) {
                $parsedRoutes[] = $generator->processRoute($route, $routeItem['apply']);
                $this->info('Processed route: ['.implode(',', $generator->getMethods($route)).'] '.$generator->getUri($route));
            } else {
                $this->warn('Skipping route: ['.implode(',', $generator->getMethods($route)).'] '.$generator->getUri($route));
            }
        }

        return $parsedRoutes;
    }

    /**
     * @param $route
     *
     * @return bool
     */
    private function isValidRoute(Route $route)
    {
        return ! is_callable($route->getAction()['uses']) && ! is_null($route->getAction()['uses']);
    }

    /**
     * @param $route
     *
     * @throws ReflectionException
     *
     * @return bool
     */
    private function isRouteVisibleForDocumentation($route)
    {
        list($class, $method) = explode('@', $route);
        $reflection = new ReflectionClass($class);

        if (! $reflection->hasMethod($method)) {
            return false;
        }

        $comment = $reflection->getMethod($method)->getDocComment();

        $allowedTags = str_replace(',,', ',', $this->option('only-tags'));
        $disallowedTags = str_replace(',,', ',', $this->option('skip-tags'));

        $allowedTags = trim($allowedTags) ? explode(',', $allowedTags) : [];
        $disallowedTags = trim($disallowedTags) ? explode(',', $disallowedTags) : [];

        if ($comment) {
            $phpdoc = new DocBlock($comment);

            if (count($allowedTags) && ! $phpdoc->hasTag('tags')) {
                return false;
            }

            return collect($phpdoc->getTags())
                ->filter(function ($tag) use ($route, $allowedTags, $disallowedTags) {
                    if ((count($allowedTags) || count($disallowedTags)) &&
                        $tag->getName() == 'tags') {
                        $tags = explode(' ', $tag->getContent());
                        $containedAllowedTags = array_intersect($tags, $allowedTags);
                        $containedDisallowedTags = array_intersect($tags, $disallowedTags);

                        return ! count($containedAllowedTags) || count($containedDisallowedTags);
                    }

                    return $tag->getName() === 'hideFromAPIDocumentation';
                })
                ->isEmpty();
        } elseif (count($allowedTags)) {
            return false;
        }

        return true;
    }

    /**
     * Generate Postman collection JSON file.
     *
     * @param Collection $routes
     *
     * @return string
     */
    private function generatePostmanCollection(Collection $routes)
    {
        $writer = new CollectionWriter($routes);

        return $writer->getCollection();
    }
}


1			<?php
2
3			namespace Mpociot\ApiDoc\Commands;
4
5			use ReflectionClass;
6			use ReflectionException;
7			use Illuminate\Routing\Route;
8			use Illuminate\Console\Command;
9			use Mpociot\Reflection\DocBlock;
10			use Illuminate\Support\Collection;
11			use Mpociot\ApiDoc\Tools\Generator;
12			use Mpociot\ApiDoc\Tools\RouteMatcher;
13			use Mpociot\Documentarian\Documentarian;
14			use Mpociot\ApiDoc\Postman\CollectionWriter;
15
16			class GenerateDocumentation extends Command
17			{
18			/**
19			* The name and signature of the console command.
20			*
21			* @var string
22			*/
23			protected $signature = 'apidoc:generate
24			{--force : Force rewriting of existing routes}
25			{--only-tags= : Comma-separated list of tags to generate}
26			{--skip-tags= : Comma-separated list of tags to skip}
27			';
28
29			/**
30			* The console command description.
31			*
32			* @var string
33			*/
34			protected $description = 'Generate your API documentation from existing Laravel routes.';
35
36			private $routeMatcher;
37
38			public function __construct(RouteMatcher $routeMatcher)
39			{
40			parent::__construct();
41			$this->routeMatcher = $routeMatcher;
42			}
43
44			/**
45			* Execute the console command.
46			*
47			* @return void
48			*/
49			public function handle()
50			{
51			$usingDingoRouter = strtolower(config('apidoc.router')) == 'dingo';
52			if ($usingDingoRouter) {
53			$routes = $this->routeMatcher->getDingoRoutesToBeDocumented(config('apidoc.routes'));
54			} else {
55			$routes = $this->routeMatcher->getLaravelRoutesToBeDocumented(config('apidoc.routes'));
56			}
57
58			$generator = new Generator();
59			$parsedRoutes = $this->processRoutes($generator, $routes);
60			$parsedRoutes = collect($parsedRoutes)->groupBy('group')
61			->sortBy(static function ($group) {
62			/* @var $group Collection */
63			return $group->first()['group'];
64			}, SORT_NATURAL);
65
66			$this->writeMarkdown($parsedRoutes);
67			}
68
69			/**
70			* @param Collection $parsedRoutes
71			*
72			* @return void
73			*/
74			private function writeMarkdown($parsedRoutes)
75			{
76			$outputPath = config('apidoc.output');
77			$targetFile = $outputPath.DIRECTORY_SEPARATOR.'source'.DIRECTORY_SEPARATOR.'index.md';
78			$compareFile = $outputPath.DIRECTORY_SEPARATOR.'source'.DIRECTORY_SEPARATOR.'.compare.md';
79			$prependFile = $outputPath.DIRECTORY_SEPARATOR.'source'.DIRECTORY_SEPARATOR.'prepend.md';
80			$appendFile = $outputPath.DIRECTORY_SEPARATOR.'source'.DIRECTORY_SEPARATOR.'append.md';
81
82			$infoText = view('apidoc::partials.info')
83			->with('outputPath', ltrim($outputPath, 'public/'))
84			->with('showPostmanCollectionButton', config('apidoc.postman'));
85
86			$parsedRouteOutput = $parsedRoutes->map(function ($routeGroup) {
87			return $routeGroup->map(function ($route) {
88			$route['output'] = (string) view('apidoc::partials.route')->with('route', $route)->render();
89
90			return $route;
91			});
92			});
93
94			$frontmatter = view('apidoc::partials.frontmatter');
95			/*
96			* In case the target file already exists, we should check if the documentation was modified
97			* and skip the modified parts of the routes.
98			*/
99			if (file_exists($targetFile) && file_exists($compareFile)) {
100			$generatedDocumentation = file_get_contents($targetFile);
101			$compareDocumentation = file_get_contents($compareFile);
102
103			if (preg_match('/---(.*)---\\s<!-- START_INFO -->/is', $generatedDocumentation, $generatedFrontmatter)) {
104			$frontmatter = trim($generatedFrontmatter[1], "\n");
105			}
106
107			$parsedRouteOutput->transform(function ($routeGroup) use ($generatedDocumentation, $compareDocumentation) {
108			return $routeGroup->transform(function ($route) use ($generatedDocumentation, $compareDocumentation) {
109			if (preg_match('/<!-- START_'.$route['id'].' -->(.*)<!-- END_'.$route['id'].' -->/is', $generatedDocumentation, $existingRouteDoc)) {
110			$routeDocumentationChanged = (preg_match('/<!-- START_'.$route['id'].' -->(.*)<!-- END_'.$route['id'].' -->/is', $compareDocumentation, $lastDocWeGeneratedForThisRoute) && $lastDocWeGeneratedForThisRoute[1] !== $existingRouteDoc[1]);
111			if ($routeDocumentationChanged === false \|\| $this->option('force')) {
112			if ($routeDocumentationChanged) {
113			$this->warn('Discarded manual changes for route ['.implode(',', $route['methods']).'] '.$route['uri']);
114			}
115			} else {
116			$this->warn('Skipping modified route ['.implode(',', $route['methods']).'] '.$route['uri']);
117			$route['modified_output'] = $existingRouteDoc[0];
118			}
119			}
120
121			return $route;
122			});
123			});
124			}
125
126			$prependFileContents = file_exists($prependFile)
127			? file_get_contents($prependFile)."\n" : '';
128			$appendFileContents = file_exists($appendFile)
129			? "\n".file_get_contents($appendFile) : '';
130
131			$documentarian = new Documentarian();
132
133			$markdown = view('apidoc::documentarian')
134			->with('writeCompareFile', false)
135			->with('frontmatter', $frontmatter)
136			->with('infoText', $infoText)
137			->with('prependMd', $prependFileContents)
138			->with('appendMd', $appendFileContents)
139			->with('outputPath', config('apidoc.output'))
140			->with('showPostmanCollectionButton', config('apidoc.postman'))
141			->with('parsedRoutes', $parsedRouteOutput);
142
143			if (! is_dir($outputPath)) {
144			$documentarian->create($outputPath);
145			}
146
147			// Write output file
148			file_put_contents($targetFile, $markdown);
149
150			// Write comparable markdown file
151			$compareMarkdown = view('apidoc::documentarian')
152			->with('writeCompareFile', true)
153			->with('frontmatter', $frontmatter)
154			->with('infoText', $infoText)
155			->with('prependMd', $prependFileContents)
156			->with('appendMd', $appendFileContents)
157			->with('outputPath', config('apidoc.output'))
158			->with('showPostmanCollectionButton', config('apidoc.postman'))
159			->with('parsedRoutes', $parsedRouteOutput);
160
161			file_put_contents($compareFile, $compareMarkdown);
162
163			$this->info('Wrote index.md to: '.$outputPath);
164
165			$this->info('Generating API HTML code');
166
167			$documentarian->generate($outputPath);
168
169			$this->info('Wrote HTML documentation to: '.$outputPath.'/index.html');
170
171			if (config('apidoc.postman')) {
172			$this->info('Generating Postman collection');
173
174			file_put_contents($outputPath.DIRECTORY_SEPARATOR.'collection.json', $this->generatePostmanCollection($parsedRoutes));
175			}
176
177			if ($logo = config('apidoc.logo')) {
178			copy(
179			$logo,
180			$outputPath.DIRECTORY_SEPARATOR.'images'.DIRECTORY_SEPARATOR.'logo.png'
181			);
182			}
183			}
184
185			/**
186			* @param Generator $generator
187			* @param array $routes
188			*
189			* @return array
190			*/
191			private function processRoutes(Generator $generator, array $routes)
192			{
193			$parsedRoutes = [];
194			foreach ($routes as $routeItem) {
195			$route = $routeItem['route'];
196			/** @var Route $route */
197			if ($this->isValidRoute($route) && $this->isRouteVisibleForDocumentation($route->getAction()['uses'])) {
198			$parsedRoutes[] = $generator->processRoute($route, $routeItem['apply']);
199			$this->info('Processed route: ['.implode(',', $generator->getMethods($route)).'] '.$generator->getUri($route));
200			} else {
201			$this->warn('Skipping route: ['.implode(',', $generator->getMethods($route)).'] '.$generator->getUri($route));
202			}
203			}
204
205			return $parsedRoutes;
206			}
207
208			/**
209			* @param $route
210			*
211			* @return bool
212			*/
213			private function isValidRoute(Route $route)
214			{
215			return ! is_callable($route->getAction()['uses']) && ! is_null($route->getAction()['uses']);
216			}
217
218			/**
219			* @param $route
220			*
221			* @throws ReflectionException
222			*
223			* @return bool
224			*/
225			private function isRouteVisibleForDocumentation($route)
226			{
227			list($class, $method) = explode('@', $route);
228			$reflection = new ReflectionClass($class);
229
230			if (! $reflection->hasMethod($method)) {
231			return false;
232			}
233
234			$comment = $reflection->getMethod($method)->getDocComment();
235
236			$allowedTags = str_replace(',,', ',', $this->option('only-tags'));
237			$disallowedTags = str_replace(',,', ',', $this->option('skip-tags'));
238
239			$allowedTags = trim($allowedTags) ? explode(',', $allowedTags) : [];
240			$disallowedTags = trim($disallowedTags) ? explode(',', $disallowedTags) : [];
241
242			if ($comment) {
243			$phpdoc = new DocBlock($comment);
244
245			if (count($allowedTags) && ! $phpdoc->hasTag('tags')) {
246			return false;
247			}
248
249			return collect($phpdoc->getTags())
250			->filter(function ($tag) use ($route, $allowedTags, $disallowedTags) {
251			if ((count($allowedTags) \|\| count($disallowedTags)) &&
252			$tag->getName() == 'tags') {
253			$tags = explode(' ', $tag->getContent());
254			$containedAllowedTags = array_intersect($tags, $allowedTags);
255			$containedDisallowedTags = array_intersect($tags, $disallowedTags);
256
257			return ! count($containedAllowedTags) \|\| count($containedDisallowedTags);
258			}
259
260			return $tag->getName() === 'hideFromAPIDocumentation';
261			})
262			->isEmpty();
263			} elseif (count($allowedTags)) {
264			return false;
265			}
266
267			return true;
268			}
269
270			/**
271			* Generate Postman collection JSON file.
272			*
273			* @param Collection $routes
274			*
275			* @return string
276			*/
277			private function generatePostmanCollection(Collection $routes)
278			{
279			$writer = new CollectionWriter($routes);
280
281			return $writer->getCollection();
282			}
283			}
284

mpociot / laravel-apidoc-generator

Pull Request — master (#439)

GenerateDocumentation::writeMarkdown() C

Complexity

Size

Duplication

Importance

How to fix Long Method Complexity

Long Method

Duplication Side-by-Side

Filter issues like