Rename reqyestHeaders stage to headers for consistency and change order

Author: shalvah

CHANGELOG.md

@@ -15,6 +15,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [4.0.0] 
 ### Added
+- Added `headers` stage (https://github.com/mpociot/laravel-apidoc-generator/pull/624)
 - Support for non-static docs, changed source files locations (https://github.com/mpociot/laravel-apidoc-generator/pull/608)
 - Support for Eloquent API resources (https://github.com/mpociot/laravel-apidoc-generator/pull/601)
 - `bindings` replaced by `@urlParam` annotation (https://github.com/mpociot/laravel-apidoc-generator/pull/599)

config/apidoc.php

@@ -172,6 +172,9 @@
         'queryParameters' => [
             \Mpociot\ApiDoc\Extracting\Strategies\QueryParameters\GetFromQueryParamTag::class,
         ],
+        'headers' => [
+            \Mpociot\ApiDoc\Extracting\Strategies\RequestHeaders\GetFromRouteRules::class,
+        ],
         'bodyParameters' => [
             \Mpociot\ApiDoc\Extracting\Strategies\BodyParameters\GetFromBodyParamTag::class,
         ],

docs/plugins.md

@@ -5,10 +5,10 @@ You can use plugins to alter how the Generator fetches data about your routes. F
 Route processing is performed in six stages:
 - metadata (this covers route `title`, route `description`, route `groupName`, route `groupDescription`, and authentication status (`authenticated`))
 - urlParameters
-- bodyParameters
 - queryParameters
+- headers (headers to be added to example request and response calls)
+- bodyParameters
 - responses
-- requestHeaeers
 
 For each stage, the Generator attempts the specified 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.
 
@@ -64,6 +64,9 @@ The last thing to do is to register the strategy. Strategies are registered in a
         'queryParameters' => [
             \Mpociot\ApiDoc\Extracting\Strategies\QueryParameters\GetFromQueryParamTag::class,
         ],
+        'headers' => [
+            \Mpociot\ApiDoc\Extracting\Strategies\RequestHeaders\GetFromRouteRules::class,
+        ],
         'bodyParameters' => [
             \Mpociot\ApiDoc\Extracting\Strategies\BodyParameters\GetFromBodyParamTag::class,
         ],
@@ -74,9 +77,6 @@ The last thing to do is to register the strategy. Strategies are registered in a
             \Mpociot\ApiDoc\Extracting\Strategies\Responses\UseApiResourceTags::class,
             \Mpociot\ApiDoc\Extracting\Strategies\Responses\ResponseCalls::class,
         ],
-        'requestHeaders' => [
-            \Mpociot\ApiDoc\Extracting\Strategies\RequestHeaders\GetFromRouteRules::class,
-        ],
     ],
 ...
 ```
@@ -173,4 +173,4 @@ Each strategy class must implement the __invoke method with the parameters as de
 
 Responses are _additive_. This means all the responses returned from each stage are added to the `responses` array. But note that the `ResponseCalls` strategy will only attempt to fetch a response if there are no responses with a status code of 2xx already.
 
-- In the `requestHeaders` stage, you can return an array of headers. You may also negate existing headers by providing `false` as the header value.
+- In the `headers` stage, you can return an array of headers. You may also negate existing headers by providing `false` as the header value.

src/Extracting/Generator.php

@@ -72,6 +72,9 @@ public function processRoute(Route $route, array $routeRules = [])
         $parsedRoute['queryParameters'] = $queryParameters;
         $parsedRoute['cleanQueryParameters'] = $this->cleanParams($queryParameters);
 
+        $headers = $this->fetchRequestHeaders($controller, $method, $route, $routeRules, $parsedRoute);
+        $parsedRoute['headers'] = $headers;
+
         $bodyParameters = $this->fetchBodyParameters($controller, $method, $route, $routeRules, $parsedRoute);
         $parsedRoute['bodyParameters'] = $bodyParameters;
         $parsedRoute['cleanBodyParameters'] = $this->cleanParams($bodyParameters);
@@ -80,9 +83,6 @@ public function processRoute(Route $route, array $routeRules = [])
         $parsedRoute['responses'] = $responses;
         $parsedRoute['showresponse'] = ! empty($responses);
 
-        $requestHeaders = $this->fetchRequestHeaders($controller, $method, $route, $routeRules, $parsedRoute);
-        $parsedRoute['headers'] = $requestHeaders;
-
         return $parsedRoute;
     }
 
@@ -128,7 +128,7 @@ protected function fetchResponses(ReflectionClass $controller, ReflectionMethod
 
     protected function fetchRequestHeaders(ReflectionClass $controller, ReflectionMethod $method, Route $route, array $rulesToApply, array $context = [])
     {
-        $headers = $this->iterateThroughStrategies('requestHeaders', $context, [$route, $controller, $method, $rulesToApply]);
+        $headers = $this->iterateThroughStrategies('headers', $context, [$route, $controller, $method, $rulesToApply]);
 
         return array_filter($headers);
     }
@@ -145,6 +145,9 @@ protected function iterateThroughStrategies(string $stage, array $context, array
             'queryParameters' => [
                 \Mpociot\ApiDoc\Extracting\Strategies\QueryParameters\GetFromQueryParamTag::class,
             ],
+            'headers' => [
+                \Mpociot\ApiDoc\Extracting\Strategies\RequestHeaders\GetFromRouteRules::class,
+            ],
             'bodyParameters' => [
                 \Mpociot\ApiDoc\Extracting\Strategies\BodyParameters\GetFromBodyParamTag::class,
             ],
@@ -155,9 +158,6 @@ protected function iterateThroughStrategies(string $stage, array $context, array
                 \Mpociot\ApiDoc\Extracting\Strategies\Responses\UseApiResourceTags::class,
                 \Mpociot\ApiDoc\Extracting\Strategies\Responses\ResponseCalls::class,
             ],
-            'requestHeaders' => [
-                \Mpociot\ApiDoc\Extracting\Strategies\RequestHeaders\GetFromRouteRules::class,
-            ],
         ];
 
         // Use the default strategies for the stage, unless they were explicitly set

src/Extracting/Strategies/Responses/ResponseCalls.php

@@ -41,7 +41,7 @@ public function __invoke(Route $route, \ReflectionClass $controller, \Reflection
         $bodyParameters = array_merge($context['cleanBodyParameters'], $rulesToApply['bodyParams'] ?? []);
         $queryParameters = array_merge($context['cleanQueryParameters'], $rulesToApply['queryParams'] ?? []);
         $urlParameters = $context['cleanUrlParameters'];
-        $request = $this->prepareRequest($route, $rulesToApply, $urlParameters, $bodyParameters, $queryParameters, $routeRules['headers'] ?? []);
+        $request = $this->prepareRequest($route, $rulesToApply, $urlParameters, $bodyParameters, $queryParameters, $context['headers'] ?? []);
 
         try {
             $response = $this->makeApiCall($request);

tests/Unit/GeneratorTestCase.php

@@ -29,6 +29,9 @@ abstract class GeneratorTestCase extends TestCase
             'queryParameters' => [
                 \Mpociot\ApiDoc\Extracting\Strategies\QueryParameters\GetFromQueryParamTag::class,
             ],
+            'headers' => [
+                \Mpociot\ApiDoc\Extracting\Strategies\RequestHeaders\GetFromRouteRules::class,
+            ],
             'bodyParameters' => [
                 \Mpociot\ApiDoc\Extracting\Strategies\BodyParameters\GetFromBodyParamTag::class,
             ],
@@ -39,9 +42,6 @@ abstract class GeneratorTestCase extends TestCase
                 \Mpociot\ApiDoc\Extracting\Strategies\Responses\UseApiResourceTags::class,
                 \Mpociot\ApiDoc\Extracting\Strategies\Responses\ResponseCalls::class,
             ],
-            'requestHeaders' => [
-                \Mpociot\ApiDoc\Extracting\Strategies\RequestHeaders\GetFromRouteRules::class,
-            ],
         ],
         'default_group' => 'general',
     ];