#scrambledrop: September 2024

September 29, 2024

Better form requests documentation, `@default` support for JSON API resources, avoiding empty request body documentation.

Hey!

In September, I’ve released few Scramble versions and due to all of them being released as minor updates, I decided to pack it all up in this single blog post.

This month’s updates include @default annotation support in JSON API resources, avoiding empty request body documentation, correct support for cases when both inline validation and form requests are used. Also, during this month few nasty issues were fixed: in some cases internal types were mutated which may’ve resulted in documentation from one operation leaking into other one.

Support usage of form requests and inline validation at the same time

Here is the example:

class PostsController
{
    public function store(ProjectRequest $request)
    {
        $request->validate([
            'title' => ['required', 'string'],
            'body' => ['required', 'string'],
        ]);
        // ...
    }
}

class ProjectRequest
{
    public function rules()
    {
        return [
            'project_id' => ['required', Rule::exists(Project::class, 'id')],
        ];
    }
}

Here users can create a post in a project. Validation rules for post are defined inline (call to validate in a controller), and a rule for project ID is defined in a form request’s class rules method.

Previously Scramble behaved unpredictably in this case: it mutated the ProjectRequest schema, so it contained post-related rules anywhere it was used. Now the issue is fixed and Scramble correctly documents the API using allOf schema:

{
  "requestBody": {
    "allOf": [
      {"$ref": "#/schemas/ProjectRequest"},
      {"type": "object", "properties": {...}, "required": ["title", "body"]}
    ]
  }
}

Ability to specify default values in JSON API resources

Now you can specify default values of attributes of JSON API resources using @default annotation:

class PostResource
{
    public function toArray(Request $request)
    {
        return [
            'title' => $this->resource->title,
            /** @default false */
            'is_published' => $this->resource->is_published,
        ];
    }
}

Avoiding empty request body annotations

Previously, when there were no validation rules or anything that defined a shape of the request, Scramble still documented the request body as an empty object. Now, when there is no rules or anything, the request body will not be added to the resulting documentation.

Fixes

• Fixed accidentally mutating types when working with types
• Using decodeURIComponent instead of decodeURI to better support Sanctum
• Fixed incorrect data wrap key when using AnonymousResourceCollection and redefining it in collected resource
• Fixes possible undefined array index 0 due to array_filter()

Thanks!

Hope you like it! Feel free to leave some stars on GitHub!

Thanks!