You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
❌ metadata are invisible in the Responses section of the endpoint documentation
❌ DTOs of metadata do not have a Schema generated
In order for the documentation to work properly, you have to:
manually construct a schema and an example value for the metadata (e.g. decorate and modify - in a very complex way - at least SchemaFactory, OpenApiFactory etc) so that an "Example response" corresponds with actual response schema.
annotate the DTO of metadata with a "fake" ApiResource and expose no operations on it, so that the DTO is recognized in the "Schema" section of the docs.
Risk that whenever someone modifies the metadata DTO, they will forget to update the docs accordingly as well 👎
Ideal solution
Allow to implement a custom collection, e.g. CustomPaginator that can contain other properties.
#[GetCollection(
provider: CollectionProvider, // built-in or custom, doesn't matter
output: ItemDTO::class, // optionally, hydrate a DTO instead of an entity
collectionOutput: CustomPaginator::class, // pass the hydrated entities/DTOs to a custom collection instance
)]
The custom paginator needs to conform to the PaginatorInterface, but can define arbitrary properties. The items are passed into it using something like a new, PaginatedItemsInterface:
classCustomPaginatorimplements \IteratorAggregate, PaginatorInterface, PaginatedItemsInterface
{
// ...public readonly CustomMetadataDTO$metadata,
// ...// Dictated by PaginatedItemsInterface, called when `collectionOutput: CustomPaginator::class` is specifiedpublicfunctionsetItems(array$items): void
{
// e.g. $this->items = $items; store and/or modify the items somehow
}
}
The remaining piece of puzzle - some mechanism needs to serialize the Paginator, generate the schema&docs, ...
Rather than manually serializing the collection, as happens now in multiple places:
Instead:
create a built-in strategy for each format (jsonld, json etc) that adds the hydra:*** annotations for jsonld, completely ignores metadata for json, etc.
introspects any additional public properties/getters (metadata) on the custom paginator, correctly builds its schema for the docs (jsonld) or ignores the metadata completely (json), ...
reacted with thumbs up emoji reacted with thumbs down emoji reacted with laugh emoji reacted with hooray emoji reacted with confused emoji reacted with heart emoji reacted with rocket emoji reacted with eyes emoji
-
Hi. I love API Platform and would like to use it on a commercial project.
However, there is one major flaw I found while experimenting with it 😢 there is no reasonable mechanism to add metadata to collection responses.
The
hydra
standard allows for arbitrary metada on collections. I tried all possible approaches over a week...Recommended solution
Currently, it is recommended to compose/decorate a Normalizer, e.g.
Problems:
❌ metadata are invisible in the Responses section of the endpoint documentation
❌ DTOs of metadata do not have a Schema generated
In order for the documentation to work properly, you have to:
SchemaFactory
,OpenApiFactory
etc) so that an "Example response" corresponds with actual response schema.ApiResource
and expose no operations on it, so that the DTO is recognized in the "Schema" section of the docs.Ideal solution
Allow to implement a custom collection, e.g.
CustomPaginator
that can contain other properties.The custom paginator needs to conform to the
PaginatorInterface
, but can define arbitrary properties. The items are passed into it using something like a new,PaginatedItemsInterface
:The remaining piece of puzzle - some mechanism needs to serialize the Paginator, generate the schema&docs, ...
Rather than manually serializing the collection, as happens now in multiple places:
Instead:
jsonld
,json
etc) that adds thehydra:***
annotations forjsonld
, completely ignores metadata forjson
, etc.jsonld
) or ignores the metadata completely (json
), ...Example of the final outcome
Facet search built with ElasticSearch:
Schema for the Example response docs is automatically generated:
Actual response is properly built with correct IRIs for metadata as well:
Beta Was this translation helpful? Give feedback.
All reactions