Merge branch 'master' into feature/nullable

shalvah · web-flow · commit 1dd06a27f432 · 2024-10-03T13:48:21.000+02:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -12,6 +12,35 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ### Removed
 
+# 4.37.2 (30 August 2024)
+## Fixed
+- Stop response fields from overflowing to the dark box zone [#868](https://github.com/knuckleswtf/scribe/pull/868)
+- Don't ignore comments for validator parameters with non string/array (e.g. conditional) rule lists [#880](https://github.com/knuckleswtf/scribe/pull/880)
+- Allow custom output path for static and external_static instead of only static [#884](https://github.com/knuckleswtf/scribe/pull/884)
+
+
+# 4.37.1 (11 July 2024)
+## Fixed
+- Multipart file upload in `elements` theme [#864](https://github.com/knuckleswtf/scribe/pull/864)
+- Properly set multiple responses in OpenAPI spec with the same status code [#863](https://github.com/knuckleswtf/scribe/pull/863)
+
+
+
+# 4.37.0 (17 June 2024)
+## Added
+- Support multiple responses in OpenAPI spec using oneOf [#739](https://github.com/knuckleswtf/scribe/pull/739)
+
+
+# 4.36.0 (27 May 2024)
+## Added
+- Add `afterResponseCall` hook [#847](https://github.com/knuckleswtf/scribe/pull/847)
+
+## Fixed
+- Unescape tryItOutBaseURL [09b49b582](https://github.com/knuckleswtf/scribe/commit/09b49b5829647597825b2cc7162382e926d53f90)
+- Ignore `external.html_attributes` for upgrades [f56a48014](https://github.com/knuckleswtf/scribe/commit/f56a480140d25ada8a441f69db9a6a14b5f0dcd1)
+- Fix missing title and logo in `elements` theme [#844](https://github.com/knuckleswtf/scribe/pull/844)
+
+
 # 4.35.0 (26 March 2024)
 ## Modified
 - Allow examples to be shown in response fields [#825](https://github.com/knuckleswtf/scribe/pull/825)
diff --git a/config/scribe.php b/config/scribe.php
@@ -241,7 +241,13 @@
             Strategies\Responses\UseResponseFileTag::class,
             [
                 Strategies\Responses\ResponseCalls::class,
-                ['only' => ['GET *']]
+                [
+                    'only' => ['GET *'],
+                    // Disable debug mode when generating response calls to avoid error stack traces in responses
+                    'config' => [
+                        'app.debug' => false,
+                    ],
+                ]
             ]
         ],
         'responseFields' => [
diff --git a/resources/css/theme-default.style.css b/resources/css/theme-default.style.css
@@ -688,6 +688,7 @@ html {
 .content>p,
 .content>table,
 .content>ul,
+.content>div,
 .content>form>aside,
 .content>form>details,
 .content>form>h1,
@@ -893,6 +894,11 @@ html {
     text-shadow: 0 1px 2px rgba(0, 0, 0, .4)
 }
 
+.content blockquote pre.sf-dump,
+.content pre pre.sf-dump {
+    width: 100%;
+}
+
 .content .annotation {
     background-color: #292929;
     color: #fff;
@@ -961,20 +967,6 @@ html {
     .page-wrapper .lang-selector {
         display: none
     }
-    .content aside,
-    .content dl,
-    .content h1,
-    .content h2,
-    .content h3,
-    .content h4,
-    .content h5,
-    .content h6,
-    .content ol,
-    .content p,
-    .content table,
-    .content ul {
-        margin-right: 0
-    }
     .content>aside,
     .content>details,
     .content>dl,
@@ -988,6 +980,7 @@ html {
     .content>p,
     .content>table,
     .content>ul,
+    .content>div,
     .content>form>aside,
     .content>form>details,
     .content>form>h1,
diff --git a/resources/js/tryitout.js b/resources/js/tryitout.js
@@ -139,18 +139,30 @@ function handleResponse(endpointId, response, status, headers) {
 
     const responseContentEl = document.querySelector('#execution-response-content-' + endpointId);
 
+    // Check if the response contains Laravel's  dd() default dump output
+    const isLaravelDump = response.includes('Sfdump');
+
+    // If it's a Laravel dd() dump, use innerHTML to render it safely
+    if (isLaravelDump) {
+        responseContentEl.innerHTML = response === '' ? responseContentEl.dataset.emptyResponseText : response;
+    } else {
+        // Otherwise, stick to textContent for regular responses
+        responseContentEl.textContent = response === '' ? responseContentEl.dataset.emptyResponseText : response;
+    }
+
     // Prettify it if it's JSON
     let isJson = false;
     try {
         const jsonParsed = JSON.parse(response);
         if (jsonParsed !== null) {
             isJson = true;
             response = JSON.stringify(jsonParsed, null, 4);
+            responseContentEl.textContent = response;
         }
     } catch (e) {
 
     }
-    responseContentEl.textContent = response === '' ? responseContentEl.dataset.emptyResponseText : response;
+
     isJson && window.hljs.highlightElement(responseContentEl);
     const statusEl = document.querySelector('#execution-response-status-' + endpointId);
     statusEl.textContent = ` (${status})`;
diff --git a/resources/views/external/elements.blade.php b/resources/views/external/elements.blade.php
@@ -4,7 +4,7 @@
 <head>
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
-    <title>Elements in HTML</title>
+    <title>{!! $metadata['title'] !!}</title>
     <!-- Embed elements Elements via Web Component -->
     <script src="https://unpkg.com/@stoplight/elements/web-components.min.js"></script>
     <link rel="stylesheet" href="https://unpkg.com/@stoplight/elements/styles.min.css">
@@ -25,7 +25,9 @@
     router="hash"
     layout="sidebar"
     hideTryIt="{!! ($tryItOut['enabled'] ?? true) ? '' : 'true'!!}"
+@if(!empty($metadata['logo']))
     logo="{!! $metadata['logo'] !!}"
+@endif
 />
 
 </body>
diff --git a/resources/views/themes/elements/components/field-details.blade.php b/resources/views/themes/elements/components/field-details.blade.php
@@ -49,12 +49,12 @@ class="svg-inline--fa fa-chevron-right fa-fw fa-sm sl-icon" role="img"
                 @endif
             </div>
         @endif
-        @if(!$hasChildren && !is_null($example) && $example != '')
+        @if(!$hasChildren && !is_null($example) && $example !== '')
             <div class="sl-stack sl-stack--horizontal sl-stack--2 sl-flex sl-flex-row sl-items-baseline sl-text-muted">
                 <span>Example:</span> <!-- <span> important for spacing -->
                 <div class="sl-flex sl-flex-1 sl-flex-wrap" style="gap: 4px;">
                     <div class="sl-max-w-full sl-break-all sl-px-1 sl-bg-canvas-tint sl-text-muted sl-rounded sl-border">
-                        {{ is_array($example) ? json_encode($example) : $example }}
+                        {{ is_array($example) || is_bool($example) ? json_encode($example) : $example }}
                     </div>
                 </div>
             </div>
diff --git a/resources/views/themes/elements/index.blade.php b/resources/views/themes/elements/index.blade.php
@@ -111,6 +111,11 @@ function tryItOut(btnElement) {
                     });
                 }
 
+                // content type has to be unset otherwise file upload won't work
+                if (form.dataset.hasfiles === "1") {
+                    delete headers['Content-Type'];
+                }
+
                 return preflightPromise.then(() => makeAPICall(method, path, body, query, headers, endpointId))
                     .then(([responseStatus, statusText, responseContent, responseHeaders]) => {
                         responsePanel.hidden = false;
@@ -132,6 +137,9 @@ function tryItOut(btnElement) {
                             }
                         } catch (e) {}
 
+                        // Replace HTML entities
+                        responseContent = responseContent.replace(/[<>&]/g, (i) => '&#' + i.charCodeAt(0) + ';');
+
                         contentEl.innerHTML = responseContent;
                         isJson && window.hljs.highlightElement(contentEl);
                     })
diff --git a/src/Commands/GenerateDocumentation.php b/src/Commands/GenerateDocumentation.php
@@ -178,7 +178,7 @@ protected function upgradeConfigFileIfNeeded(): void
             )
                 ->dontTouch(
                     'routes', 'example_languages', 'database_connections_to_transact', 'strategies', 'laravel.middleware',
-                    'postman.overrides', 'openapi.overrides', 'groups', 'examples.models_source'
+                    'postman.overrides', 'openapi.overrides', 'groups', 'examples.models_source', 'external.html_attributes'
                 );
             $changes = $upgrader->dryRun();
             if (!empty($changes)) {
diff --git a/src/Commands/Upgrade.php b/src/Commands/Upgrade.php
@@ -43,7 +43,7 @@ public function handle(): void
 
         $upgrader = Upgrader::ofConfigFile("config/$this->configName.php", __DIR__ . '/../../config/scribe.php')
             ->dontTouch('routes', 'laravel.middleware', 'postman.overrides', 'openapi.overrides',
-                'example_languages', 'database_connections_to_transact', 'strategies', 'examples.models_source')
+                'example_languages', 'database_connections_to_transact', 'strategies', 'examples.models_source', 'external.html_attributes')
             ->move('default_group', 'groups.default')
             ->move('faker_seed', 'examples.faker_seed');
 
diff --git a/src/Extracting/DatabaseTransactionHelpers.php b/src/Extracting/DatabaseTransactionHelpers.php
@@ -15,9 +15,9 @@ private function connectionsToTransact()
 
     private function startDbTransaction()
     {
-        $database = app('db');
-
         foreach ($this->connectionsToTransact() as $connection) {
+            $database ??= app('db');
+
             $driver = $database->connection($connection);
 
             if (self::driverSupportsTransactions($driver)) {
@@ -30,7 +30,6 @@ private function startDbTransaction()
                         " If you aren't using this database, remove it from the `database_connections_to_transact` config array."
                     );
                 }
-                continue;
             } else {
                 $driverClassName = get_class($driver);
                 throw DatabaseTransactionsNotSupported::create($connection, $driverClassName);
@@ -43,9 +42,9 @@ private function startDbTransaction()
      */
     private function endDbTransaction()
     {
-        $database = app('db');
-
         foreach ($this->connectionsToTransact() as $connection) {
+            $database ??= app('db');
+
             $driver = $database->connection($connection);
             try {
                 $driver->rollback();
diff --git a/src/Extracting/Extractor.php b/src/Extracting/Extractor.php
@@ -215,23 +215,24 @@ protected function iterateThroughStrategies(
                 }
 
                 $settings = self::transformOldRouteRulesIntoNewSettings($stage, $rulesToApply, $strategyClass, $settings);
-                $routesToSkip = $settings["except"] ?? [];
-                $routesToInclude = $settings["only"] ?? [];
-
-                if (!empty($routesToSkip)) {
-                    if (RoutePatternMatcher::matches($endpointData->route, $routesToSkip)) {
-                        continue;
-                    }
-                } elseif (!empty($routesToInclude)) {
-                    if (!RoutePatternMatcher::matches($endpointData->route, $routesToInclude)) {
-                        continue;
-                    }
-                }
             } else {
                 $strategyClass = $strategyClassOrTuple;
                 $settings = self::transformOldRouteRulesIntoNewSettings($stage, $rulesToApply, $strategyClass);
             }
 
+            $routesToSkip = $settings["except"] ?? [];
+            $routesToInclude = $settings["only"] ?? [];
+
+            if (!empty($routesToSkip)) {
+                if (RoutePatternMatcher::matches($endpointData->route, $routesToSkip)) {
+                    continue;
+                }
+            } elseif (!empty($routesToInclude)) {
+                if (!RoutePatternMatcher::matches($endpointData->route, $routesToInclude)) {
+                    continue;
+                }
+            }
+
             $strategy = new $strategyClass($this->config);
             $results = $strategy($endpointData, $settings);
             if (is_array($results)) {
diff --git a/src/Extracting/ParsesValidationRules.php b/src/Extracting/ParsesValidationRules.php
@@ -540,6 +540,9 @@ protected function parseRule($rule, array &$parameterData, bool $independentOnly
                 case 'nullable':
                     $parameterData['nullable'] = true;
                     break;
+                case 'exists':
+                    $parameterData['description'] .= " The <code>{$arguments[1]}</code> of an existing record in the {$arguments[0]} table.";
+                    break;
                 default:
                     // Other rules not supported
                     break;
@@ -644,8 +647,11 @@ public function convertGenericArrayType(array $parameters): array
                 // 2. If `users.<name>` exists, `users` is an `object`
                 // 3. Otherwise, default to `object`
                 // Important: We're iterating in reverse, to ensure we set child items before parent items
-                // (assuming the user specified parents first, which is the more common thing)
-                if ($childKey = Arr::first($allKeys, fn($key) => Str::startsWith($key, "$name.*"))) {
+                // (assuming the user specified parents first, which is the more common thing)y
+                if(Arr::first($allKeys, fn($key) => Str::startsWith($key, "$name.*."))) {
+                    $details['type'] = 'object[]';
+                    unset($details['setter']);
+                } else if ($childKey = Arr::first($allKeys, fn($key) => Str::startsWith($key, "$name.*"))) {
                     $childType = ($converted[$childKey] ?? $parameters[$childKey])['type'];
                     $details['type'] = "{$childType}[]";
                 } else { // `array` types default to `object` if no subtype is specified
diff --git a/src/Extracting/Strategies/GetFromInlineValidatorBase.php b/src/Extracting/Strategies/GetFromInlineValidatorBase.php
@@ -81,7 +81,6 @@ public function lookForInlineValidationRules(ClassMethod $methodAst): array
                     if ($arrayItem->value instanceof Node\Scalar\String_) {
                         $rulesList[] = $arrayItem->value->value;
                     }
-
                     // Try to extract Enum rule
                     else if (
                         function_exists('enum_exists') &&
@@ -97,7 +96,6 @@ enum_exists($enum) && method_exists($enum, 'tryFrom')
                 $rules[$paramName] = join('|', $rulesList);
             } else {
                 $rules[$paramName] = [];
-                continue;
             }
 
             $dataFromComment = [];
diff --git a/src/Extracting/Strategies/GetParamsFromAttributeStrategy.php b/src/Extracting/Strategies/GetParamsFromAttributeStrategy.php
@@ -34,7 +34,7 @@ protected function normalizeParameterData(array $data): array
                 'name' => $data['name'],
                 'enumValues' => $data['enumValues'],
             ]);
-        } else if ($data['example'] == 'No-example' || $data['example'] == 'No-example.') {
+        } else if ($data['example'] === 'No-example' || $data['example'] === 'No-example.') {
             $data['example'] = null;
         }
 
diff --git a/src/Extracting/Strategies/Responses/ResponseCalls.php b/src/Extracting/Strategies/Responses/ResponseCalls.php
@@ -2,8 +2,6 @@
 
 namespace Knuckles\Scribe\Extracting\Strategies\Responses;
 
-use Illuminate\Support\Facades\Config;
-use Knuckles\Camel\Extraction\ExtractedEndpointData;
 use Dingo\Api\Dispatcher;
 use Dingo\Api\Routing\Route as DingoRoute;
 use Exception;
@@ -12,7 +10,9 @@
 use Illuminate\Http\Response;
 use Illuminate\Http\UploadedFile;
 use Illuminate\Routing\Route;
+use Illuminate\Support\Facades\Config;
 use Illuminate\Support\Str;
+use Knuckles\Camel\Extraction\ExtractedEndpointData;
 use Knuckles\Scribe\Extracting\DatabaseTransactionHelpers;
 use Knuckles\Scribe\Extracting\ParamHelpers;
 use Knuckles\Scribe\Extracting\Strategies\Strategy;
@@ -89,6 +89,9 @@ public function makeResponseCall(ExtractedEndpointData $endpointData, array $set
 
         try {
             $response = $this->makeApiCall($request, $endpointData->route);
+
+            $this->runPostRequestHook($request, $endpointData, $response);
+
             $response = [
                 [
                     'status' => $response->getStatusCode(),
@@ -170,6 +173,13 @@ protected function runPreRequestHook(Request $request, ExtractedEndpointData $en
         }
     }
 
+    protected function runPostRequestHook(Request $request, ExtractedEndpointData $endpointData, mixed $response): void
+    {
+        if (is_callable(Globals::$__afterResponseCall)) {
+            call_user_func_array(Globals::$__afterResponseCall, [$request, $endpointData, $response]);
+        }
+    }
+
     private function setLaravelConfigs(array $config)
     {
         if (empty($config)) {
diff --git a/src/Scribe.php b/src/Scribe.php
@@ -9,7 +9,7 @@
 
 class Scribe
 {
-    public const VERSION = '4.35.0';
+    public const VERSION = '4.37.2';
 
     /**
      * Specify a callback that will be executed just before a response call is made
@@ -22,6 +22,17 @@ public static function beforeResponseCall(callable $callable)
         Globals::$__beforeResponseCall = $callable;
     }
 
+    /**
+     * Specify a callback that will be executed just after a response call is done
+     * (allowing to modify the response).
+     *
+     * @param callable(Request, ExtractedEndpointData, mixed): mixed $callable
+     */
+    public static function afterResponseCall(callable $callable)
+    {
+        Globals::$__afterResponseCall = $callable;
+    }
+
     /**
      * Specify a callback that will be executed just before the generate command is executed
      *
diff --git a/src/Tools/Globals.php b/src/Tools/Globals.php
diff --git a/src/Writing/HtmlWriter.php b/src/Writing/HtmlWriter.php
diff --git a/src/Writing/OpenAPISpecWriter.php b/src/Writing/OpenAPISpecWriter.php
diff --git a/src/Writing/PostmanCollectionWriter.php b/src/Writing/PostmanCollectionWriter.php
diff --git a/tests/Unit/ExtractorTest.php b/tests/Unit/ExtractorTest.php
diff --git a/tests/Unit/OpenAPISpecWriterTest.php b/tests/Unit/OpenAPISpecWriterTest.php
diff --git a/tests/Unit/ValidationRuleParsingTest.php b/tests/Unit/ValidationRuleParsingTest.php

Original file line number	Diff line number	Diff line change
`@@ -178,7 +178,7 @@ protected function upgradeConfigFileIfNeeded(): void`
`178`	`178`	`)`
`179`	`179`	`->dontTouch(`
`180`	`180`	`'routes', 'example_languages', 'database_connections_to_transact', 'strategies', 'laravel.middleware',`
`181`		`- 'postman.overrides', 'openapi.overrides', 'groups', 'examples.models_source'`
	`181`	`+ 'postman.overrides', 'openapi.overrides', 'groups', 'examples.models_source', 'external.html_attributes'`
`182`	`182`	`);`
`183`	`183`	`$changes = $upgrader->dryRun();`
`184`	`184`	`if (!empty($changes)) {`