knuckleswtf / knuckleswtf/scribe
Dedicated support for Laravel 13's first-party JsonApiResource
- Dominant language
- PHP
- Stars
- 2.3k
- Forks
- 357
- PR merge metrics
- No merged PRs in 30d
Description
### Scribe version
5.9
### Your question
## Context
Laravel 13 shipped first-party JSON:API support through `Illuminate\Http\Resources\JsonApi\JsonApiResource`. It extends the regular JsonResource, so Scribe doesn't crash on it, but the generated response isn't quite right, and I think we can close that gap with a small, focused change.
## Two possible approaches
### Minimal fix (correct response rendering)
Detect when the resource extends JsonApiResource, build the synthetic request with `?include= populated` from the resource's declared relationships (and optionally `?fields[type]=` for full coverage), and switch the Accept header to `application/vnd.api+json`. The existing pipeline handles the rest. Small, self-contained, lives inside `ApiResourceResponseTools`.
### Broader fix (above + query parameter documentation)
Same response fix, plus a strategy that auto-documents the JSON:API query params for each endpoint: include as an enum of available relationships, fields[type] per resource type. This requires reflection on `toRelationships()` and handling nested includes, so it's more code and more design decisions, but it gives users a spec that matches how JSON:API consumers actually call the API.
## Questions
Before I start working on a PR, I'd rather hear which direction (if any) feels right to you:
- Is approach 1 welcome on its own?
- Would you prefer approach 2, or would you rather land 1 first and treat the query-param piece as a separate follow-up?
- Anything about the architecture or extension surface I should know about before diving in?
I'd be happy to work on a PR for either approach, just let me know which one fits best with where you want Scribe to go.
### Docs
- [x] I've checked [the docs](https://scribe.knuckles.wtf/laravel), the [troubleshooting guide](https://scribe.knuckles.wtf/laravel/troubleshooting), and [existing issues](https://github.com/knuckleswtf/scribe/issues?q=is%3Aissue+), but I didn't find a solution
Contributor guide
Research direction
Start in ApiResourceResponseTools and inspect how regular JsonResource responses are rendered. Confirm the intended scope before changing the synthetic request and Accept header for JsonApiResource; done means generated JSON:API responses correctly reflect declared relationships, with query-parameter documentation included only if that broader approach is selected.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- laravel, php
- Domain
- api, backend
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100