knuckleswtf / knuckleswtf/scribe

Generate Response Fields from @apiResource or #[ResponseFromApiResource]

Open
#596 2 comments 0 reactions 0 assignees View on GitHub
question
Dominant language
PHP
Stars
2.3k
Forks
357
PR merge metrics
No merged PRs in 30d

Description

- [x] I've read the [documentation](https://scribe.knuckles.wtf/laravel) and I can't find details on how to achieve this.
- [x] I almost know the section [Responses](https://scribe.knuckles.wtf/laravel/documenting/responses) by heart

I very much like the option to autogenerate an example response from a given API Resources and Models because it reduces code duplicity.
But I would love if scribe would generate ResponseField (with name and type) from the API Resource / the Model (instead of just example responses).

In the following I describe an excerpt of my results so far and how I would like them to be:
- I have
- a model called `Rating`,
- a route `GET api/ratings` and
- a Controller Method `RatingController::all()` where a ResourceCollection (`RatingCollection::class)` is returned.

```php
'int',
'userID' => 'int',
'bikeID' => 'int'
];

protected $fillable = [
'score',
'userID',
'bikeID'
];

public function bike()
{
return $this->belongsTo(Bike::class, 'bikeID');
}

public function user()
{
return $this->belongsTo(User::class, 'userID');
}
}
```

```php
Route::get("ratings", [RatingController::class, 'all'])->name('ratings.get');
```

```php
/**
* @group Ratings
* API to create or update and read bike ratings
*/
class RatingController extends Controller
{
/**
* GET ratings
*
* user sees a list of all ratings for all bikes (since a certain time)
*/
#[QueryParam('sinceDate', 'date', 'time from which the ratings were submitted', required: false, example: '2023-04-26T12:30:00')]
#[ResponseFromApiResource(RatingCollection::class, Rating::class)]
public function all(FormRequests\Rating\GetAllRequest $request)
{
$validated = $request->validated();
$ratings = Rating::where('updated_at', '>=', date("Y-m-d H:i:s", strtotime($validated['sinceDate'])))->get();
return new JsonResponse(new RatingCollection($ratings), 200, [], 0);
}
}
```

I get the following result:
Screenshot 2023-01-04 at 01 14 59

I would love this result (without manually adding ResponseFields):
Screenshot 2023-01-04 at 01 22 12

Contributor guide

Open the contributing guide

Research direction

Start by tracing how #[ResponseFromApiResource] handles RatingCollection::class and Rating::class, then inspect the existing response example generation path. Done means the generated response includes field names and types from the API resource or model for the shown collection case, without manual ResponseField declarations.

Written by the indexing model from the issue text.

Assessment

Tech stack
laravel, php
Domain
api, backend, documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.