docs: Enhance Json schema documentation

[ES-Six]

This PR is intended to improve the JSON Schema documentation to specify the Overriding JSON Schema specification use case (usefull when making unit tests).

This PR concern an already existing functionnality that was undocumented.

[dunglas]

Nice addition.

[ES-Six]

All requested changes have been taken into account.

[ES-Six]

Do not hesitate if you need additional changes or improvements 😉.

[ES-Six]

Requested changes are now applied.

[alanpoulain]

Are you sure? OpenAPI and JSON Schema should be fully compatible now.

[ES-Six]

I tested it while doing unit tests and using the assertMatchesResourceCollectionJsonSchema method and while testing on an entity with JSON column in it.

For this doctrine JSON column, I was using the openapi_context "type" => "json" to make it appear well in the documentation. But in a unit testing context, the JSON Schema automatically generated ignore the openapi_context.

Example of api property used in my project :

#[ApiProperty(attributes: [
        "openapi_context" => [
            "type" => "json",
            "example"=>"{...json content here...}"
        ]
    ])]

So I tried to set the JSON schema to "type" => "json".
Like this :
Example of api property used in my project :

#[ApiProperty(attributes: [
        "openapi_context" => [
            "type" => "json",
            "example"=>"{...json content here...}"
        ],
        "json_schema_context" => [
            "type" => "json"
        ]
    ])]

But it doesn't work because the type JSON is not a part of the JSON Schema specification, so unit test fails as it take the default type for this context inside API Platform instead.

Available JSON Schema types are : http://json-schema.org/understanding-json-schema/reference/type.html

So to solve the problem in this specific case, I need to use the type to make the unit test to pass

#[ApiProperty(attributes: [
        "openapi_context" => [
            "type" => "json",
            "example"=>"{...json content here...}"
        ],
        "json_schema_context" => [
            "type" => "array"
        ]
    ])]

It also seems to display well the example in the swagger doc, when I specify "type" => "array" for both, but the generated openapi schema is not correct on the swagger doc :

With "type" => "json" in the openapi_context the schema in the swagger do appear like this (excpected behaviour) :

With "type" => "array" in the openapi_context the schema in the swagger do appear like this (not the excpected behaviour) :

So the JSON Schema and OpenAPI seems not to have the exact same types in APIPlatform, so my initial intention is also to document this exeption in order to allow users to handle JSON column in their entities.

[alanpoulain]

I don't think json type is a valid data type. Swagger UI simply displays it by default as a string.

[ES-Six]

Are you sure? OpenAPI and JSON Schema should be fully compatible now.

I don't think json type is a valid data type. Swagger UI simply displays it by default as a string.

As I investigated more here is what I understood :

Yes, OpenAPI and JSON Schema are fully compatible. So I need to change the doc. Indeed I miss understood these 2 specifications.

The type property is only an informative text OR if it's a known value (example : string, integer, array, object, etc...) it will be used to handle specific things on the swagger doc.

Example :

#[ApiProperty(attributes: [
    "openapi_context" => [
        "type" => "json" // This is an informative text as it's an invalid data type
        // As no items is specified, swagger use a default "items" => ["type" => "string"] and rely on it as fallback
    ]
])]

So if "type" is an informative text by default, we can put anything we want in this property, so it is an unknown data type but it's a valid property.

So I only need to delete this problematic part because it's erroneous.

[ES-Six]

This erroneous part is now removed, sorry for this error, I had trouble understanding what is exactly the purpose of the "type" property :)

[ES-Six]

Requested changes are now applied.

[alanpoulain]

Thank you @ES-Six.