[feature] Allow for multiple `@status` responses

[MarnuLombard]

• By allowing for parsing more than one @status doc-block we can export the same response under one code
• This is especially useful as Laravel Resources will return status code 201 is the underlying model wasRecentlyCreated

[romalytvynenko]

I don't really understand the motivation behind this feature.

[MarnuLombard]

Hi @romalytvynenko Any upsert endpoint could return a 200 OR a 201 response based on whether the Model::$wasRecentlyCreated is true or not. In fact that is the default behaviour of Laravel when converting a resource to a response.

There is no way (currently) to document that behaviour using scramble.

This code modifies no current behaviour of the library (manual @status doc-blocks are still respected), but adds the feature of displaying a response under multiple status codes.

[MarnuLombard]

Hi @romalytvynenko

Will this be merged?

[romalytvynenko]

@MarnuLombard I was considering to merge, but manual response attributes were coming so I've waited on it.

I've just added #[Response] attribute (it will be available in the next release) that will allow to do the following:

#[Response(201, type: OrderResource::class)]
public function createOrUpdate(Request $request)
{
    $data = $request->validate([
        'name' => 'string',
    ]);
    
    $order = Order::updateOrCreate(...);
       
    return OrderResource::make($order);
}

This example will add a new 201 response of OrderResource (so you will have both 200 and 201 response).

While not really as optimal as your suggested approach (as you need to manually specify the type), I believe it should do the job.

[MarnuLombard]

@romalytvynenko Your solution does indeed solve the issue I was having, thank you.