Beter Collection metadata extension #2696
signor-pedro
started this conversation in
Ideas
Replies: 0 comments
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
-
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