Merge branch 'knuckleswtf:master' into master

knuckleswtf · Sep 17, 2023 · 409b25f · 409b25f
2 parents 821cf83 + 6b4715b
commit 409b25f
Show file tree

Hide file tree

Showing 11 changed files with 122 additions and 16 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -12,9 +12,18 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ### Removed
 
+# 4.24.0 (16 September 2023)
+## Added
+- Support dependency injection in FormRequests ([84078358ce](https://github.com/knuckleswtf/scribe/commit/84078358ce32ff0656a9ab03f062e952f721f1a2))
+- Include `auth.extra_info` in OpenAPI security scheme ([#727](https://github.com/knuckleswtf/scribe/pull/727))
+- Support dynamic base URL ([#723](https://github.com/knuckleswtf/scribe/pull/723))
+
+## Fixed
+- Generate proper sample for array of objects ([#720](https://github.com/knuckleswtf/scribe/pull/720))
+
 # 4.23.1 (25 August 2023)
 ## Fixed
-- Break in attributes due to enum support ([4c49e81e0](https://github.com/knuckleswtf/scribe/commit/6a9d51b3a215a89e8b8af47f796ffaa10993c171))
+- Break in attributes due to enum support ([4c49e81e0](https://github.com/knuckleswtf/scribe/commit/4c49e81e0a6f4a257c3945a139b9a3bf35d85b2b))
 
 # 4.23.0 (24 August 2023)
 ## Added

diff --git a/config/scribe.php b/config/scribe.php
@@ -17,7 +17,8 @@
     'description' => '',
 
     /*
-     * The base URL displayed in the docs. If this is empty, Scribe will use the value of config('app.url').
+     * The base URL displayed in the docs. If this is empty, Scribe will use the value of config('app.url') at generation time.
+     * If you're using `laravel`` type, you can set this to a dynamic string, like '{{ config("app.tenant_url") }}' to get a dynamic base URL.
      */
     'base_url' => null,
 
@@ -189,7 +190,7 @@
 
         /**
          * The base URL for the API tester to use (for example, you can set this to your staging URL).
-         * Leave as null to use the current app URL (config(app.url)).
+         * Leave as null to use the current app URL when generating (config("app.url")).
          */
         'base_url' => null,
 

diff --git a/resources/views/partials/example-requests/bash.md.blade.php b/resources/views/partials/example-requests/bash.md.blade.php
@@ -4,7 +4,7 @@
 @endphp
 ```bash
 curl --request {{$endpoint->httpMethods[0]}} \
-    {{$endpoint->httpMethods[0] == 'GET' ? '--get ' : ''}}"{{ rtrim($baseUrl, '/')}}/{{ ltrim($endpoint->boundUri, '/') }}@if(count($endpoint->cleanQueryParameters))?{!! u::printQueryParamsAsString($endpoint->cleanQueryParameters) !!}@endif"@if(count($endpoint->headers)) \
+    {{$endpoint->httpMethods[0] == 'GET' ? '--get ' : ''}}"{!! rtrim($baseUrl, '/') !!}/{{ ltrim($endpoint->boundUri, '/') }}@if(count($endpoint->cleanQueryParameters))?{!! u::printQueryParamsAsString($endpoint->cleanQueryParameters) !!}@endif"@if(count($endpoint->headers)) \
 @foreach($endpoint->headers as $header => $value)
     --header "{{$header}}: {{ addslashes($value) }}"@if(! ($loop->last) || ($loop->last && count($endpoint->bodyParameters))) \
 @endif

diff --git a/resources/views/partials/example-requests/javascript.md.blade.php b/resources/views/partials/example-requests/javascript.md.blade.php
@@ -4,7 +4,7 @@
 @endphp
 ```javascript
 const url = new URL(
-    "{{ rtrim($baseUrl, '/') }}/{{ ltrim($endpoint->boundUri, '/') }}"
+    "{!! rtrim($baseUrl, '/') !!}/{{ ltrim($endpoint->boundUri, '/') }}"
 );
 @if(count($endpoint->cleanQueryParameters))
 
@@ -53,7 +53,7 @@
     body,
 @elseif(count($endpoint->cleanBodyParameters))
 @if ($endpoint->headers['Content-Type'] == 'application/x-www-form-urlencoded')
-    body: body,
+    body,
 @else
     body: JSON.stringify(body),
 @endif

diff --git a/resources/views/partials/example-requests/php.md.blade.php b/resources/views/partials/example-requests/php.md.blade.php
@@ -4,9 +4,10 @@
 @endphp
 ```php
 $client = new \GuzzleHttp\Client();
+$url = '{!! rtrim($baseUrl, '/') . '/' . ltrim($endpoint->boundUri, '/') !!}';
 @if($endpoint->hasHeadersOrQueryOrBodyParams())
 $response = $client->{{ strtolower($endpoint->httpMethods[0]) }}(
-    '{{ rtrim($baseUrl, '/') . '/' . ltrim($endpoint->boundUri, '/') }}',
+    $url,
     [
 @if(!empty($endpoint->headers))
         'headers' => {!! u::printPhpValue($endpoint->headers, 8) !!},
@@ -43,7 +44,7 @@
     ]
 );
 @else
-$response = $client->{{ strtolower($endpoint->httpMethods[0]) }}('{{ rtrim($baseUrl, '/') . '/' . ltrim($endpoint->boundUri, '/') }}');
+$response = $client->{{ strtolower($endpoint->httpMethods[0]) }}($url);
 @endif
 $body = $response->getBody();
 print_r(json_decode((string) $body));

diff --git a/resources/views/partials/example-requests/python.md.blade.php b/resources/views/partials/example-requests/python.md.blade.php
@@ -6,7 +6,7 @@
 import requests
 import json
 
-url = '{{ rtrim($baseUrl, '/') }}/{{ $endpoint->boundUri }}'
+url = '{!! rtrim($baseUrl, '/') !!}/{{ $endpoint->boundUri }}'
 @if($endpoint->hasFiles() || (isset($endpoint->headers['Content-Type']) && $endpoint->headers['Content-Type'] == 'multipart/form-data' && count($endpoint->cleanBodyParameters)))
 files = {
 @foreach($endpoint->cleanBodyParameters as $parameter => $value)

diff --git a/src/Scribe.php b/src/Scribe.php
@@ -9,7 +9,7 @@
 
 class Scribe
 {
-    public const VERSION = '4.23.1';
+    public const VERSION = '4.24.0';
 
     /**
      * Specify a callback that will be executed just before a response call is made

diff --git a/src/Tools/WritingUtils.php b/src/Tools/WritingUtils.php
@@ -218,6 +218,10 @@ public static function getSampleBody(array $nestedBodyParameters)
 
         return array_map(function ($param) {
             if (!empty($param['__fields'])) {
+                if ($param['type'] === 'object[]') {
+                    return [self::getSampleBody($param['__fields'])];
+                }
+
                 return self::getSampleBody($param['__fields']);
             }
 

diff --git a/src/Writing/OpenAPISpecWriter.php b/src/Writing/OpenAPISpecWriter.php
@@ -403,18 +403,18 @@ protected function generateSecurityPartialSpec(): array
 
         $location = $this->config->get('auth.in');
         $parameterName = $this->config->get('auth.name');
-
+        $description = $this->config->get('auth.extra_info');
         $scheme = match ($location) {
             'query', 'header' => [
                 'type' => 'apiKey',
                 'name' => $parameterName,
                 'in' => $location,
-                'description' => '',
+                'description' => $description,
             ],
             'bearer', 'basic' => [
                 'type' => 'http',
                 'scheme' => $location,
-                'description' => '',
+                'description' => $description,
             ],
             default => [],
         };

diff --git a/tests/Unit/OpenAPISpecWriterTest.php b/tests/Unit/OpenAPISpecWriterTest.php
@@ -80,15 +80,22 @@ public function adds_authentication_details_correctly_as_security_info()
         $endpointData1 = $this->createMockEndpointData(['uri' => 'path1', 'httpMethods' => ['GET'], 'metadata.authenticated' => true]);
         $endpointData2 = $this->createMockEndpointData(['uri' => 'path1', 'httpMethods' => ['POST'], 'metadata.authenticated' => false]);
         $groups = [$this->createGroup([$endpointData1, $endpointData2])];
-
-        $config = array_merge($this->config, ['auth' => ['enabled' => true, 'in' => 'bearer']]);
+        $extraInfo = "When stuck trying to authenticate, have a coffee!";
+        $config = array_merge($this->config, [
+            'auth' => [
+                'enabled' => true,
+                'in' => 'bearer',
+                'extra_info' => $extraInfo,
+            ],
+        ]);
         $writer = new OpenAPISpecWriter(new DocumentationConfig($config));
         $results = $writer->generateSpecContent($groups);
 
         $this->assertCount(1, $results['components']['securitySchemes']);
         $this->assertArrayHasKey('default', $results['components']['securitySchemes']);
         $this->assertEquals('http', $results['components']['securitySchemes']['default']['type']);
         $this->assertEquals('bearer', $results['components']['securitySchemes']['default']['scheme']);
+        $this->assertEquals($extraInfo, $results['components']['securitySchemes']['default']['description']);
         $this->assertCount(1, $results['security']);
         $this->assertCount(1, $results['security'][0]);
         $this->assertArrayHasKey('default', $results['security'][0]);
@@ -97,13 +104,21 @@ public function adds_authentication_details_correctly_as_security_info()
         $this->assertCount(0, $results['paths']['/path1']['post']['security']);
 
         // Next try: auth with a query parameter
-        $config = array_merge($this->config, ['auth' => ['enabled' => true, 'in' => 'query', 'name' => 'token']]);
+        $config = array_merge($this->config, [
+            'auth' => [
+                'enabled' => true,
+                'in' => 'query',
+                'name' => 'token',
+                'extra_info' => $extraInfo,
+            ],
+        ]);
         $writer = new OpenAPISpecWriter(new DocumentationConfig($config));
         $results = $writer->generateSpecContent($groups);
 
         $this->assertCount(1, $results['components']['securitySchemes']);
         $this->assertArrayHasKey('default', $results['components']['securitySchemes']);
         $this->assertEquals('apiKey', $results['components']['securitySchemes']['default']['type']);
+        $this->assertEquals($extraInfo, $results['components']['securitySchemes']['default']['description']);
         $this->assertEquals($config['auth']['name'], $results['components']['securitySchemes']['default']['name']);
         $this->assertEquals('query', $results['components']['securitySchemes']['default']['in']);
         $this->assertCount(1, $results['security']);

diff --git a/tests/Unit/WritingUtilsTest.php b/tests/Unit/WritingUtilsTest.php
@@ -78,6 +78,25 @@ public function print_query_params_as_string_bash()
         $this->assertEquals($expected, $queryParams);
     }
 
+    /** @test */
+    public function get_sample_body_with_array_fields()
+    {
+        $sampleBody = WritingUtils::getSampleBody($this->bodyParamsWithArrayFields());
+
+        $expected = [
+            'name' => 'Experience Form',
+            'fields' => [
+                [
+                    'name' => 'experience',
+                    'label' => 'Experience',
+                    'type' => 'textarea',
+                    'order' => 1,
+                ],
+            ],
+        ];
+        $this->assertEquals($expected, $sampleBody);
+    }
+
     private function queryParams(): array
     {
         return [
@@ -99,6 +118,63 @@ private function queryParams(): array
         ];
     }
 
+    private function bodyParamsWithArrayFields(): array
+    {
+        return [
+            'name' => [
+                'name' => 'name',
+                'description' => 'Form\'s name',
+                'required' => true,
+                'example' => 'Experience Form',
+                'type' => 'string',
+                'custom' => [],
+                '__fields' => [],
+            ],
+            'fields' => [
+                'name' => 'fields',
+                'description' => 'Form\'s fields',
+                'required' => false,
+                'example' => [[]],
+                'type' => 'object[]',
+                'custom' => [],
+                '__fields' => [
+                    'name' => [
+                        'name' => 'fields[].name',
+                        'description' => 'Field\'s name',
+                        'required' => true,
+                        'example' => 'experience',
+                        'type' => 'string',
+                        'custom' => [],
+                    ],
+                    'label' => [
+                        'name' => 'fields[].label',
+                        'description' => 'Field\'s label',
+                        'required' => true,
+                        'example' => 'Experience',
+                        'type' => 'string',
+                        'custom' => [],
+                    ],
+                    'type' => [
+                        'name' => 'fields[].type',
+                        'description' => 'Field\'s type',
+                        'required' => true,
+                        'example' => 'textarea',
+                        'type' => 'string',
+                        'custom' => [],
+                    ],
+                    'order' => [
+                        'name' => 'fields[].order',
+                        'description' => 'Field\'s order',
+                        'required' => true,
+                        'example' => 1,
+                        'type' => 'number',
+                        'custom' => [],
+                    ],
+                ],
+            ],
+        ];
+    }
+
     protected function assertStringsEqualNormalizingNewlines(string $expected, string $actual)
     {
         $this->assertEquals(str_replace("\r", "", $expected), str_replace("\r", "", $actual));