knuckleswtf / knuckleswtf/scribe

Dedicated support for Laravel 13's first-party JsonApiResource

Open
#1,073 0 comments 3 reactions 0 assignees View on GitHub
question triage
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.