January 11, 2023
Added multiple servers support, URL variables support, ability to document request body params in validation rules and more awesome improvements.
Hey Laravel community!
I am 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.7.0 is out: https://github.com/dedoc/scramble/releases/tag/v0.7.0
Here are cool things I’ve added in this release.
From now you can add descriptions, examples, and override types for request params. It is useful when Scramble doesn’t generate docs properly, or when you want to be more specific in your documentation.
It works both for validate
calls in your controller’s methods and for custom FormRequest
classes.
To document a request param, simply add PHPDoc (or a comment) before the corresponding validation rule.
class TodoController
{
public function store(Request $request)
{
$request->validate([
/**
* The todo item text.
*
* @example This is the todo item.
*/
'body' => ['required', 'string'],
// Whether the todo item is completed.
'is_completed' => ['required', 'bool'],
/**
* The location coordinates associated with todo item.
*
* @var array{lat: float, long: float}
* @example {"lat": 50.450001, "long": 30.523333}
*/
'coordinates' => 'array',
]);
// ...
}
}
Read more about it in documentation: https://scramble.dedoc.co/usage/request#documenting-request-params-manually
From now, you can add multiple API servers in your documentation. This will allow to try out endpoints from UI on different servers.
For example, you can have local server and a production one, to try things out.
To do so, simply define servers
in Scramble config.
Read more about multiple servers support in the docs: https://scramble.dedoc.co/digging-deeper/servers#multiple-servers
In Laravel it is possible to use some part of a domain as a parameter. Prior to 0.7.0 Scramble didn’t document this properly.
So if you have multi-tenant application and your tenants have their own domains (for example, {tenant}.yourapi.com
, Scramble will document it properly.
<?php // routes/api.php
Route::domain('{subdomain}.'.config('app.domain'))->group(function () {
Route::apiResource('todo-item', \App\Http\Controllers\TodoItemController::class)->only([
'index',
'store',
'show',
'destroy',
]);
// ...
You can learn more about server variable support and how to add a description to the server variable in the docs: https://scramble.dedoc.co/digging-deeper/servers#server-variables
Now, using abort helpers (abort
, abort_if
, abort_unless
) will add corresponding error responses automatically. The cool thing, is that if you’ve specified a string literal as your message, Scramble will use it as an example for your documentation.
JsonResource
s in the resource class, added support of 3rd argument in when
and whenLoaded
in #87
null
able in #74
@var
in #75
exceptions
property on possibly nullable object in #95
phpDoc
attributes on resolved type attached by PhpDocHandler
when they're attached to pending type in #96
doctrine/dbal
is not installed in #99
Hope you like it! If so, please share this update on Twitter (share button is on the right).
Thanks!