Scramble 0.8.0 - Update of Laravel API documentation generator

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