#scrambledrop: Scramble 0.10.0

March 15, 2024

Customize documentation URL, register multiple API documentation websites, document request parameter examples and more!

Hey!

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.

0.10.0 is a big Scramble update that brings ability to customize docs URL, to register multiple API documentations websites, to document examples and more! And finally it’s released: is out: https://github.com/dedoc/scramble/releases/tag/v0.10.0

Customizing documentation URL

Now you can customize domain and path for your documentation. Yeah, a bit overdue, but better late than never!

For example, here is how you can register your documentation website on a custom subdomain.

Scramble::ignoreDefaultRoutes();

// routes/web.php
Route::domain('myapp.com', function () {
    Scramble::registerUiRoute('api-docs');
    Scramble::registerJsonSpecificationRoute('api-docs.json');
});

Now, documentation website will be available on myapp.com/api-docs and JSON specification on myapp.com/api-docs.json.

Multiple API versions documentation

This version introduces one of the most requested features: ability to define docs for multiple API versions, customized docs path or domain.

It allows you to have a documentation for every API version you have in your project.

Scramble::ignoreDefaultRoutes();

Scramble::registerApi('v1', [
    'api_path' => 'api/v1',
]);

Scramble::registerApi('v2', [
    'api_path' => 'api/v2',
]);

// routes/web.php
Scramble::registerUiRoute(path: 'docs-v1', api: 'v1');
Scramble::registerJsonSpecificationRoute(path: 'docs-v1.json', api: 'v1');

Scramble::registerUiRoute(path: 'docs-v2', api: 'v2');
Scramble::registerJsonSpecificationRoute(path: 'docs-v2.json', api: 'v2');

This will disable default API documentation URL and make 2 different API documentations, for v1 and v2 respectively, available on specified routes.

Learn more: https://scramble.dedoc.co/usage/multiple-docs

Examples, defaults, marking request parameter as part of query

0.10.0 brings few improvements to request parameters documentation: now you can provide examples, default values, and mark a parameter as a part of query string (for non-GET requests).

Providing examples also work for API resources.

Also Scramble now documents all calls to Request objects in controller as request parameter with corresponding type. So $request->integer('limit', 15); line will result in limit parameter documented as int with default value 15 in documentation!

Learn more: https://scramble.dedoc.co/usage/request#method-calls-on-a-request-object

Improved Sanctum integration

Now “Try it” feature works with Sanctum’s cookie-based API out of the box.

Ability to customize generated operations’ tags

By default Scramble uses controller’s class name as a tag, so in UI all routes defined in the controller are grouped.

Now you can override that behavior and specify your own tags generation logic.

Tuples support

Tuple is a data structure that describe an ordered sequence of values. In Scramble 0.10.0 you can document tuples and provide examples for them.

Other changes

• Add support for enums in route parameter;
• Improved 204 empty responses documentation;
• Determine eloquent attribute type from casts;
• Fix confirmed rule not working properly when it is used on multiple attributes;
• Type inference in ternaries;
• Remove request body from HEAD and DELETE by default;
• Fixed validation rules being documented differently depending on rules order.

Thanks!

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

Thanks!