Generate Laravel HTTP Client Examples with Mintlify & Scribe

README.md

Getting Started

Make the File

Copy the LaravelHttpSamplesGenerator.php file and place it in app/Docs/Generators directory. Create the folders if they don't exist.

Update Config

In your config/scribe.php make sure to add the class to your generators array within the openapi section.

 // Additional generators to use when generating the OpenAPI spec.
 // Should extend `Knuckles\Scribe\Writing\OpenApiSpecGenerators\OpenApiGenerator`.
        'generators' => [
            LaravelHttpSamplesGenerator::class,
        ],

Update Mintlify docs.json

Make sure it includes php in the array otherwise the docs won't show the snippet.

This will replace the default PHP CURL example that Mintlify provides, there doesn't seem to be a way to have them both, at least not without modifying the openapi.yaml file further.

 "api": {
    "examples": {
      "languages": ["curl", "php", "javascript"]
    },

Run Scribe

Now run Scribe and make sure the openapi.yaml file can be read by Mintlify. If you open the file you should see x-codeSamples throughout the yaml file, indicating that the generator has included Laravel examples.

You're all done!

Credits

Thanks to the Mintlify docs - https://www.mintlify.com/docs/api-playground/adding-sdk-examples

LaravelHttpSamplesGenerator.php

<?php

declare(strict_types=1);

namespace App\Docs\Generators;

use Knuckles\Camel\Output\OutputEndpointData;
use Knuckles\Scribe\Writing\OpenApiSpecGenerators\OpenApiGenerator;

class LaravelHttpSamplesGenerator extends OpenApiGenerator
{
    public function pathItem(array $pathItem, array $groupedEndpoints, OutputEndpointData $endpoint): array
    {
        $laravelExample = $this->generateLaravelHttpExample($endpoint);

        $pathItem['x-codeSamples'] ??= [];

        $pathItem['x-codeSamples'][] = [
            'lang' => 'php',
            'label' => 'Laravel HTTP Client',
            'source' => $laravelExample,
        ];

        return $pathItem;
    }

    protected function generateLaravelHttpExample(OutputEndpointData $endpoint): string
    {
        $method = strtolower($endpoint->httpMethods[0]);
        $baseUrl = rtrim($this->config->get('base_url'), '/');
        $url = $baseUrl . '/' . ltrim($endpoint->uri, '/');

        foreach ($endpoint->urlParameters as $name => $param) {
            $url = str_replace('{' . $name . '}', '{' . $name . '}', $url);
        }

        $code = "use Illuminate\\Support\\Facades\\Http;\n\n";
        $code .= "\$url = \"{$url}\";\n\n";

        $chain = 'Http::';

        if ($endpoint->metadata->authenticated) {
            $chain .= "withToken('<token>')";
        }

        $chain .= "\n    ->{$method}(\$url";

        $dataParams = [];
        $isBodyMethod = in_array($method, ['post', 'put', 'patch', 'delete']);

        if ($isBodyMethod && ! empty($endpoint->bodyParameters)) {
            foreach ($endpoint->bodyParameters as $name => $param) {
                $dataParams[$name] = $param->example;
            }
        } elseif (! empty($endpoint->queryParameters)) {
            foreach ($endpoint->queryParameters as $name => $param) {
                $dataParams[$name] = $param->example;
            }
        }

        if (! empty($dataParams)) {
            $formattedArray = $this->formatArrayValue($dataParams, 2);
            $chain .= ", {$formattedArray}";
        }

        $chain .= ');';

        $code .= "\$response = {$chain}";

        return $code;
    }

    protected function formatExampleValue($value): string
    {
        if (is_null($value)) {
            return 'null';
        }

        if (is_bool($value)) {
            return $value ? 'true' : 'false';
        }

        if (is_numeric($value)) {
            return (string) $value;
        }

        if (is_array($value)) {
            return $this->formatArrayValue($value);
        }

        return "'" . addslashes((string) $value) . "'";
    }

    protected function formatArrayValue(array $value, int $depth = 0): string
    {
        if (empty($value)) {
            return '[]';
        }

        $indent = str_repeat('    ', $depth);
        $innerIndent = str_repeat('    ', $depth + 1);
        $items = [];

        $isAssoc = array_keys($value) !== range(0, count($value) - 1);

        foreach ($value as $key => $val) {
            $formattedVal = is_array($val)
                ? $this->formatArrayValue($val, $depth + 1)
                : $this->formatExampleValue($val);

            if ($isAssoc) {
                $formattedKey = is_string($key) ? "'{$key}'" : $key;
                $items[] = "{$innerIndent}{$formattedKey} => {$formattedVal},";
            } else {
                $items[] = "{$innerIndent}{$formattedVal},";
            }
        }

        return "[\n" . implode("\n", $items) . "\n{$indent}]";
    }
}