OpenAPI v3: generate specific JSON Schemas for JSON-LD, JSON:API...

[dunglas]

Unlike OpenAPI v2, OpenAPI v3 allows to specify different JSON Schema per MIME type. It would now be possible to document the format-specific reserved keys such as @id and @type in JSON-LD, and the format specific structures such as hydra:member and the errors using OpenAPI.

It would be a nice addition.

[MyDigitalLife]

@dunglas Could you specify a bit how this can be achieved? If so I might try and add some schema's for json:api when I have some free time.

[dunglas]

Hi @MyDigitalLife, the response object can now contain a specific JSON Schema per content: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#response-object

The idea would be to modify https://github.com/api-platform/core/blob/master/src/Swagger/Serializer/DocumentationNormalizer.php#L180 to generate a specific JSON Schema for the JSON-LD response that includes the definition for @id, @type hydra:member and so on. Later, we would do the same for other formats having specific structures (JSON:API and HAL).

[MyDigitalLife]

I just did some digging and found a way to do this. Took some searching but i can now define a format for a MimeType and when selecting a new you it switches. You can see my work in progress here: master...MyDigitalLife:mime-type-components-schema

I will be updating it so that the other operations also use the new formats and will most likely will move the generation of the definition schema to its own class so new format can easily be added.

@dunglas Got any comments on what I'm doing so far?

[dunglas]

@MyDigitalLife sorry I hadn't reviewed your work yet, but I think that it's very important to have this supported. Would you mind opening a PR directly so it will be easier to review.

[DrummerKH]

Hello, could you answer, please, when this feature will be released?

[dunglas]

@DrummerKH when someone will finish the open PR or contribute a new one.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.