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

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