[Laravel / JSON:API] Request body OpenAPI docs ignore serialization groups

[cay89]

API Platform version(s) affected: 4.1.18

Description

When using serialization groups, request body documentation doesn't match actual API behavior:

• API behavior: POST request ignores relationships (respects denormalizationContext groups)
• OpenAPI docs: POST request body shows relationships (ignores groups)

class ListType extends AbstractModel
{
    use IsApiResource;

    /** @use HasFactory<ListTypeFactory> */
    use HasFactory;

    protected $fillable = ['label', 'status'];

    protected function casts(): array
    {
        return [
            'status' => ListTypeStatus::class,
            'global' => 'boolean',
        ];
    }

    /**
     * @return HasMany<ListItem, $this>
     */
    public function listitems(): HasMany
    {
        return $this->hasMany(ListItem::class, 'type_key', 'key');
    }
   
    #[Groups(['list-type:read'])]
    public function getListitems() {
        return $this->listitems;
    }

    #[Groups(['list-type:read', 'list-type:write'])]
    public function getStatus(): ListTypeStatus {
        return $this->status;
    }

    #[Groups(['list-type:read', 'list-type:write'])]
    public function getLabel(): ?string {
        return $this->label;
    }

    public static function apiResource(): array
    {
        return [
            new ApiResource(
                operations: [
                    new GetCollection(
                        normalizationContext: ['groups' => ['list-type:read']],
                    ),
                    new Post(
                        normalizationContext: ['groups' => ['list-type:write']],
                        denormalizationContext: ['groups' => ['list-type:write']],
                    ),
                ]
            )
        ];
    }
}

Result

POST response correctly excludes relationships, but OpenAPI request body example still shows them.

Proposed Solution

The request body documentation should respect the denormalizationContext serialization groups, similar to how response documentation respects normalizationContext groups.

Ideally, when a POST operation is configured with:

new Post(
    denormalizationContext: ['groups' => ['list-type:write']],
)

The generated OpenAPI request body schema should only include fields that belong to the list-type:write group.

Impact

This inconsistency leads to:

• Developer confusion
• Incorrect client code generation

This issue affects the core principle that documentation should accurately reflect API behavior. When documentation and behavior diverge, it undermines developer trust and creates maintenance overhead.

Would it be possible to implement serialization group support for request body documentation, or is there a recommended pattern we should follow to achieve consistent documentation?

[PicassoHouessou]

Hello,

With Eloquent, serialization groups work with ApiProperty.

You can’t use groups directly because Eloquent models don’t have properties.

Check this section in the docs: https://api-platform.com/docs/laravel/#relations-and-nested-resources

Here’s a quick example:

namespace App\Models;

use ApiPlatform\Metadata\ApiResource;
use Illuminate\Database\Eloquent\Model;

#[ApiResource(normalizationContext: ['groups' => ['book:read']])]
#[ApiProperty(serialize: new Groups(['book:read']), property: 'title')]
#[ApiProperty(serialize: new Groups(['book:read']), property: 'description')]
#[ApiProperty(serialize: new Groups(['book:read']), property: 'author')]
class Book extends Model
{
    public function author(): BelongsTo
    {
        return $this->belongsTo(Author::class);
    }
}

[cay89]

Hello,

Thank you for the suggestion! I tested the ApiProperty approach with Eloquent models as you described, but unfortunately it doesn't solve the issue.

What I tried:

#[ApiResource(
    operations: [
        new GetCollection(
            normalizationContext: ['groups' => ['list-type:read']],
        ),
        new Post(
            normalizationContext: ['groups' => ['list-type:write']],
            denormalizationContext: ['groups' => ['list-type:write']],
        ),
    ],
)]
#[ApiProperty(property: 'key', serialize: new Groups(['list-type:read', 'list-type:write']))]
#[ApiProperty(property: 'status', serialize: new Groups(['list-type:read', 'list-type:write']))]
#[ApiProperty(property: 'label', serialize: new Groups(['list-type:read', 'list-type:write']))]
#[ApiProperty(property: 'global', serialize: new Groups(['list-type:read', 'list-type:write']))]
#[ApiProperty(property: 'listitems', serialize: new Groups(['list-type:read']))]
class ListType extends Model
{
    public function listitems(): HasMany
    {
        return $this->hasMany(ListItem::class, 'type_key', 'key');
    }
}

Results:

The original issue persists. The serialization groups are still ignored for JSON:API request body documentation.

Investigation:

Looking at the generated OpenAPI spec, the POST endpoint uses different schemas for different content types:

{
  "requestBody": {
    "content": {
      "application/vnd.api+json": {
        "schema": { "$ref": "#/components/schemas/ListType.jsonapi" }
      },
      "text/html": {
        "schema": { "$ref": "#/components/schemas/ListType-list-type.write" }
      }
    }
  }
}

While the ListType-list-type.write schema correctly excludes listitems, the ListType.jsonapi schema still contains the relationships section:

{
  "relationships": {
    "listitems": {
      "properties": {
        "data": {
          "type": "array",
          "items": { ... }
        }
      }
    }
  }
}

Conclusion:

The ApiProperty + Groups approach does not solve the issue. The problem remains: serialization groups are ignored for JSON:API format schemas in OpenAPI documentation.

The API behavior itself works correctly (POST requests properly ignore relationships according to denormalizationContext), but the JSON:API documentation remains inconsistent.

[soyuka]

Indeed groups are not parsed with JSON:API because the standard way of querying the data is using include and sparse fieldset (https://jsonapi.org/format/#fetching-includes) which are incompatible with groups. The best way here is probably to design your resources first:

#[ApiResource(operations: [new GetCollection()])]
class ListItem {}

#[ApiResource(operations: [new Post()])]
class CreateItem {}

Then use providers/processors to retrieve/persist the correct data.

[cay89]

Yeah, I ended up going in this direction too. I split up the POST/PATCH endpoints and put the ApiResource on a DTO (using providers/processors) that defines what data can be sent to the write endpoints, and kept the GET (and DELETE) on the model. But honestly, this feels more like a workaround than a clean solution. It would be nicer to define everything directly on the model.