Forem: Roman

Scramble 0.11.0 – Laravel API docs generator update: Laravel Data support, enforcing schema types, inference improvements

Roman — Thu, 04 Jul 2024 12:27:21 +0000

Hey Laravel community!

I’m happy to announce a new version of Scramble. Scramble is Laravel API docs generator that generates doc without requiring you to write PHPDoc annotations: https://scramble.dedoc.co/introduction.

Laravel Data support

Finally, Scramble supports Spatie's Laravel Data package! Scramble will make a proper documentation when a data object is used as a form request. There are a lot of nuances to how data objects are actually behave in these contexts, and Scramble will handle all of them properly.

Notice how there are no PHPDoc annotations used at all, and the documentation is complete.



    use App\Data\TodoData;
    use App\Models\Todo;

    class TodoController extends Controller
    {
        public function show(Todo $todo)
        {
            return TodoData::from($todo);
        }
    }



    use Spatie\LaravelData\Data;
    use Spatie\LaravelData\Attributes\Validation\Min;
    use Spatie\LaravelData\Attributes\Validation\Max;

    class TodoData extends Data
    {
        public function __construct(
            #[Min(3), Max(255)]
            public string $title,
            public string $content,
            public bool $completed,
        ) {}
    }

Laravel Data package is supported as a part of Scramble PRO. To be able to maintain Scramble and introduce features, I'm looking for ways to monetize it. Scramble PRO is one way of doing it. The overall goal of Scramble PRO is to make sure the teams using it are successful with Scramble: the documentation generation is automatic (minimizing manual annotations and errors) and resulting documentation is as accurate as possible.

Here is a Laravel Data support documentation. There you'll find example project and example API documentation to check things out yourself!

Ability to ensure schema types

Taking into account Scramble is inferring types across the codebase and then makes a documentation based on that, you may want to know when a type is not inferred and fix that case so your documentation is as accurate as it gets.

Introducing the Scramble::preventSchema method! It is used in an application service provider.



use Dedoc\Scramble\Support\Generator\Types\UnknownType;

public function register()
{
    Scramble::preventSchema(UnknownType::class);
}

With this method Scramble will fail when generating documentation in case any of the provided schemas are met.

In case you don't want to change anything in the code to fix a particular schema, but you don't want it to be reported (thrown), you can whitelist it (similar to baseline concept of PHPStan). To whitelist an error, simply add a string pattern that will match error's JSON Pointer (found at):



Scramble::preventSchema(UnknownType::class, ignorePaths: [
    '*/PublisherImportStatusesCollection/type*',
]);

In case you want the schemas to be reported by analyze command, but you don't want it to throw an exception during the documentation generation, you can pass boolean throw parameter:



Scramble::preventSchema(UnknownType::class, throw: false);

You can add some logic, like prevent throwing the exceptions in a non-production environment:



Scramble::preventSchema(UnknownType::class, throw: ! app()->isProduction());

This highlights any type that Scramble could not infer and this highlights the HUGE amount of work in the future!

Command to analyze documentation

To see all the occurrences of prevented schemas in project, you can use php artisan scramble:analyze command:



$ php artisan scramble:analyze
POST api/brand/{brand}/creators-import 1 error .. API\BrandPublishersImportController@store

1. Schema [UnknownType] is not allowed.
Found at /components/schemas/PublisherImportStatusesCollection/type/properties/id
Inferred at App\Http\Resources\PublisherImportStatusesCollection:25
     21▕      */
     22▕     public function toArray($request)
     23▕     {
     24▕         return [
  ➜  25▕             'id' => $this->batchId,
     26▕             'progress' => $this->calculateProgress(),
     27▕             'results' => $this->collection,
     28▕         ];
     29▕     }
....

This command shows you all the occurrences of prevented schemas: the JSON pointer (Found at) of where the schema occurred in Open API document, and where possible the line of code which is responsible for this schema! So you can find and fix such things FAST.

This command can be used as a part of your CI as well.

Other

Besides the larger features, this release if full of smaller goodies as well:

Аdded the response and toResponse methods support on resource instances in #440
Fixed data transform issue for manually annotated response bodies in #493
Fix bug preventing validation rules from being documented when 3rd parameter was passing to validation methods in #410
Fixed float literals transformation in #411
Fix failing collection transformation when a resource is used in additional in #422
Fixed nullable being skipped when analyzing rules in #426
Fixed return type annotation being ignored in #434
Fixed non-needed usage of AnyOf for responses documentation when the response code is the same in #427
Moved default value from parameter to schema in #438

Thanks!

Thanks for checking this post out. If you have any questions, ideas, suggestions, feel free to drop me a line to roman@dedoc.co

Originally posted on Scramble's blog: https://scramble.dedoc.co/blog/scrambledrop-scramble-0110

Scramble 0.8.0 - Update of Laravel API documentation generator

Roman — Wed, 02 Aug 2023 07:17:14 +0000

Improved performance, type inference across the codebase, operation ID generation, and sorted docs out of the box.

Hey Laravel community!

Super happy to announce the new version of Scramble. Scramble is API documentation generator for Laravel that works without requiring you to write PHPDoc annotations: https://scramble.dedoc.co/introduction.

0.8.0 is finally out: https://github.com/dedoc/scramble/releases/tag/v0.8.0

This version requires PHP 8.1 now to work.

Performance improvements

This version took a lot of time to build, but as the result Scramble now can analyze entire codebase to infer types.

And despite analyzing the entire codebase, this release makes Scramble around 40% faster!

~40% speed improvement was measured on a big codebase with 250+ API endpoints.

Type inference across the codebase

Type inference is a process of determining types of variables based on the source code analysis.

Scramble uses type inference to understand responses of endpoints. PhpDoc usually either not accurate or outdated, and just type hints don’t contain enough information. Consider this example.

public function show(Post $post): JsonResponse
{
    return response()->json($post);
}

While type hint clearly states the response is JsonResponse, only this information won’t be useful for documentation. We’d want to know the specifics of the response.

So thanks to type inference, Scramble deducts the return type of this method to something like JsonResponse<Post, 200, []>. And now we actually have useful information here — response body, response status, headers.

Prior to 0.8.0 Scramble was pretty limited in what types it can infer. It could understand types based on info that is available in the file being analyzed, but it didn’t analyze other files.

So let’s take this example:

// Controllers/PostsController.php
public function show(int $post, PostRepository $postRepository)
{
    return $postRepository->find($post);
}

// Repositories/PostsRepository.php
public function find(int $postId): Post
{
    /* ... */
}

Prior to 0.8.0 Scramble would analyze just the controller source code, and won’t deep dive into PostRepository class to see what is going on there.

But in 0.8.0 Scramble does that! To infer the type returned from show, Scramble now will analyze PostRepository’s find method. This way it will know that controller’s show method returns Post instance, hence it can document the response correctly.

And even with deep diving into the codebase, this version is shipped with performance improvements (40% faster docs generation) 🤯

So improved type inference will cover more cases out of the box, and will allow you to have more accurate responses documentation without manual type hinting.

Notice how success method is defined in trait, and Scramble is able to deduct the final response type from it.

Operations ID support

In OpenAPI standard, operation ID is a unique identifier for an operation (endpoint). It is primarily used as link anchors in docs websites, or by code generators to generate methods names. You get the point.

Helge Sverre pointed out that operation IDs are also required by Chat GPT plugins to consume your APIs and even provided an implementation for manual operationId support in his blog! Thank you Helge!

In 0.8.0 Scramble will automatically generate unique operationId for every endpoint, and also it will allow you to have specify it yourself using @operationId PhpDoc annotation.

Operation ID is used as link anchors in current Scramble’s UI.

Read more about it in documentation: https://scramble.dedoc.co/usage/request#documenting-operation-id

Sorting pages in documentation automatically

Starting from 0.8.0 all operations (endpoints) and schemas (resources) are sorted alphabetically in the resulting documentation.

It will make reading docs more convenient and will allow to find information faster.

Other changes

Added confirmed validation rule support
Added support of UUID model keys
Fixed spread operator not being properly analyzed when inferring a type for an array

Thanks!

Hope you like it! If so, please share this update on Twitter (share button is on the right) and leave some stars in Github.

Thanks!

Originally posted on Scramble's Blog: https://blog.dedoc.co/scrambledrop-scramble-080

How to create robust HTTP clients with Guzzle

Roman — Tue, 25 May 2021 19:00:37 +0000

I never was a big fan of Guzzle until recently when I finally learned about Guzzle middleware and some basic config.

Here is how you can step up your Guzzle game and build robust HTTP clients.

First of all, start from setting timeouts. Timeouts are not limited by default, and this can cause headaches when debugging issues it can cause.

I remember spending 2 days trying to understand why some jobs randomly time-outed. It wasn't fun when I noticed some requests stuck!

use GuzzleHttp\Client;

$client = new Client([
    'timeout' => 15,
    'connect_timeout' => 15,
]);

So Guzzle's middleware stack. Guzzle passes any request through the middleware stack. It allows you to add your middleware and do something for every request (or every response): add the API key to headers, handle errors, and even retry failed requests.

To start you need to create HandlerStack. The simplest way to do it is to call the static method create on HandlerStack class. You will add middleware to the stack.

use GuzzleHttp\Client;
use GuzzleHttp\HandlerStack;

$stack = HandlerStack::create();

// ...

$client = new Client([
    'base_uri' => 'https://api.some.com',
    'timeout' => 15,
    'connect_timeout' => 15,
    'handler' => $stack,
]);

Guzzle's middleware on its own is pretty tricky: a function that returns a function. But thankfully, they've added sugar for it, so it looks readable.

Let's start from Middleware::mapRequest middleware. It allows you to modify a request. I use this middleware to add the API key to every request, either in headers or in the query string. It helps to reduce the amount of boilerplate code I write when making requests.

use GuzzleHttp\Middleware;
use GuzzleHttp\HandlerStack;
use Psr\Http\Message\RequestInterface;

$stack->push(function (RequestInterface $request) {
    $token = config('services.some.api_token');

    return $request->withHeader('Authorization', "Basic {$token}");
});

Middleware::mapResponse allows you to do something with the response. I use it to do basic error handling. This way, I can avoid excessive try/catch usage or wrapping my entire client in a separate method.

use GuzzleHttp\Middleware;
use Psr\Http\Message\ResponseInterface;

$stack->push(Middleware::mapResponse(function (ResponseInterface $response) {
    if (in_array($response->getStatusCode(), [401, 403])) {
        // Some logic to hanle the error. For example, save it into DB.
    }
    return $response;
}));

And my favorite Middleware::retry. It allows you to specify when and how to retry failed requests. For example, when you get 50x errors, connection timeouts, etc you would probably want to try again before giving up.

use Exception;
use GuzzleHttp\Middleware;
use Psr\Http\Message\RequestInterface;
use Psr\Http\Message\ResponseInterface;
use GuzzleHttp\Exception\ConnectException;

$retryDecider = function (
    $retries, 
    RequestInterface $request, 
    ResponseInterface $response = null, 
    Exception $exception = null
) {
    if ($retries >= 5) {
        return false;
    }
    if ($exception instanceof ConnectException) {
        return true;
    }
    if ($response && $response->getStatusCode() >= 500) {
        return true;
    }
    return false;
};

$retryDelay = function ($numberOfRetries) {
    return 1000 * $numberOfRetries;
};

$stack->push(Middleware::retry($retryDecider, $retryDelay));

Retry middleware also allows you to set the delay between requests so you can configure something like exponential back-off pretty easily. On the screenshot in the previous tweet delay between requests will be a bit bigger between every failed request.

At this point, you have a robust Guzzle HTTP client that is enjoyable to use. It will automatically retry failed requests, add authorization to the request, or do whatever you need!