Scramble 0.11.0 – Laravel API docs generator update: Laravel Data support, enforcing schema types, inference improvements
Tags: laravel, api, openapi, documentation
Published: 2024-07-04 12:27:21


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](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.
```php
    use App\Data\TodoData;
    use App\Models\Todo;

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

```php
    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,
        ) {}
    }
 ```

![Resulting documentation](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/vsy2pwpq892u4h6wu3vn.png)

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](/usage/laravel-data). 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.

```php
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):

```php
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:
```php
Scramble::preventSchema(UnknownType::class, throw: false);
```

You can add some logic, like prevent throwing the exceptions in a non-production environment:
```php
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:

```sh
$ 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](https://github.com/dedoc/scramble/pull/440)
* Fixed data transform issue for manually annotated response bodies in [#493](https://github.com/dedoc/scramble/pull/439)
* Fix bug preventing validation rules from being documented when 3rd parameter was passing to validation methods in [#410](https://github.com/dedoc/scramble/pull/410)
* Fixed float literals transformation in [#411](https://github.com/dedoc/scramble/pull/411)
* Fix failing collection transformation when a resource is used in `additional` in [#422](https://github.com/dedoc/scramble/pull/422)
* Fixed nullable being skipped when analyzing rules in [#426](https://github.com/dedoc/scramble/pull/426)
* Fixed return type annotation being ignored in [#434](https://github.com/dedoc/scramble/pull/434)
* Fixed non-needed usage of `AnyOf` for responses documentation when the response code is the same in [#427](https://github.com/dedoc/scramble/pull/427)
* Moved default value from parameter to schema in [#438](https://github.com/dedoc/scramble/pull/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