get headers from tags

Author: whizzrd

config/apidoc.php

@@ -215,6 +215,7 @@
         ],
         'headers' => [
             \Mpociot\ApiDoc\Extracting\Strategies\RequestHeaders\GetFromRouteRules::class,
+            \Mpociot\ApiDoc\Extracting\Strategies\RequestHeaders\GetFromHeaderTag::class,
         ],
         'bodyParameters' => [
             \Mpociot\ApiDoc\Extracting\Strategies\BodyParameters\GetFromBodyParamTag::class,

resources/views/partials/example-requests/bash.blade.php

@@ -1,7 +1,7 @@
 ```bash
 curl -X {{$route['methods'][0]}} \
     {{$route['methods'][0] == 'GET' ? '-G ' : ''}}"{{ rtrim($baseUrl, '/')}}/{{ ltrim($route['boundUri'], '/') }}@if(count($route['cleanQueryParameters']))?{!! \Mpociot\ApiDoc\Tools\Utils::printQueryParamsAsString($route['cleanQueryParameters']) !!}@endif" @if(count($route['headers']))\
-@foreach($route['headers'] as $header => $value)
+@foreach($route['cleanHeaders'] as $header => $value)
     -H "{{$header}}: {{ addslashes($value) }}"@if(! ($loop->last) || ($loop->last && count($route['bodyParameters']))) \
 @endif
 @endforeach

src/Extracting/Generator.php

@@ -76,6 +76,7 @@ public function processRoute(Route $route, array $routeRules = [])
 
         $headers = $this->fetchRequestHeaders($controller, $method, $route, $routeRules, $parsedRoute);
         $parsedRoute['headers'] = $headers;
+        $parsedRoute['cleanHeaders'] = $this->cleanHeaders($headers);
 
         $bodyParameters = $this->fetchBodyParameters($controller, $method, $route, $routeRules, $parsedRoute);
         $parsedRoute['bodyParameters'] = $bodyParameters;
@@ -222,6 +223,26 @@ protected function cleanParams(array $params)
         return $values;
     }
 
+    /**
+     * Create samples at index 0 for array parameters.
+     * Also filter out header which were excluded from having examples.
+     *
+     * @param array $params
+     *
+     * @return array
+     */
+    protected function cleanHeaders(array $params)
+    {
+        $values = [];
+
+        // Remove params which have no examples.
+        $params = array_filter($params, function ($details) {
+            return ! empty($details);
+        });
+
+        return $params;
+    }
+
     /**
      * 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.

src/Extracting/Strategies/RequestHeaders/GetFromHeaderTag.php

@@ -0,0 +1,73 @@
+<?php
+
+namespace Mpociot\ApiDoc\Extracting\Strategies\RequestHeaders;
+
+use Dingo\Api\Http\FormRequest as DingoFormRequest;
+use Illuminate\Foundation\Http\FormRequest as LaravelFormRequest;
+use Illuminate\Routing\Route;
+use Illuminate\Support\Str;
+use Mpociot\ApiDoc\Extracting\ParamHelpers;
+use Mpociot\ApiDoc\Extracting\RouteDocBlocker;
+use Mpociot\ApiDoc\Extracting\Strategies\Strategy;
+use Mpociot\Reflection\DocBlock;
+use Mpociot\Reflection\DocBlock\Tag;
+use ReflectionClass;
+use ReflectionMethod;
+
+class GetFromHeaderTag extends Strategy
+{
+    use ParamHelpers;
+
+    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 = $paramType->getName();
+
+            try {
+                $parameterClass = new ReflectionClass($parameterClassName);
+            } catch (\ReflectionException $e) {
+                continue;
+            }
+
+            // If there's a FormRequest, we check there for @urlParam tags.
+            if (class_exists(LaravelFormRequest::class) && $parameterClass->isSubclassOf(LaravelFormRequest::class)
+                || class_exists(DingoFormRequest::class) && $parameterClass->isSubclassOf(DingoFormRequest::class)) {
+                $formRequestDocBlock = new DocBlock($parameterClass->getDocComment());
+                $headersFromDocBlock = $this->getHeadersFromDocBlock($formRequestDocBlock->getTags());
+
+                if (count($headersFromDocBlock)) {
+                    return $headersFromDocBlock;
+                }
+            }
+        }
+
+        /** @var DocBlock $methodDocBlock */
+        $methodDocBlock = RouteDocBlocker::getDocBlocksFromRoute($route)['method'];
+
+        return $this->getHeadersFromDocBlock($methodDocBlock->getTags());
+    }
+
+    private function getHeadersFromDocBlock($tags)
+    {
+        $parameters = collect($tags)
+            ->filter(function ($tag) {
+                return $tag instanceof Tag && $tag->getName() === 'header';
+            })
+            ->mapWithKeys(function (Tag $tag) {
+                // Format:
+                // @header <content>
+                // Examples:
+                // @header Cookie foo Example: crumbs
+                preg_match('/(.+?)\s+(.*)/', $tag->getContent(), $content);
+                list($content, $name, $value) = $content;
+                return [$name => $value];
+            })->toArray();
+
+        return $parameters;
+    }
+}

tests/Unit/GeneratorTestCase.php

@@ -33,6 +33,7 @@ abstract class GeneratorTestCase extends TestCase
                 \Mpociot\ApiDoc\Extracting\Strategies\QueryParameters\GetFromQueryParamTag::class,
             ],
             'headers' => [
+                \Mpociot\ApiDoc\Extracting\Strategies\RequestHeaders\GetFromHeaderTag::class,
                 \Mpociot\ApiDoc\Extracting\Strategies\RequestHeaders\GetFromRouteRules::class,
             ],
             'bodyParameters' => [