Understanding SchemaFactory behavior on openapiContext on type string

[monitaurus]

Hi, I've got a property in an entity/resource which is an nullable enum of strings.
But the generated OpenAPI shows an object.

I found out that I needed to specify on openapiContext a string with a format enum:

#[ApiProperty(openapiContext: ['type' => 'string', 'format' => 'enum', nullable' => true])]
private ?CustomEnum $value = null;

But I took a look into ApiPlatform\JsonSchema\SchemaFactory and found out this condition, and this line:

        if (
            !$isUnknown && (
                [] === $types
                || ($propertySchema['$ref'] ?? $propertySchema['anyOf'] ?? $propertySchema['allOf'] ?? $propertySchema['oneOf'] ?? false)
                # this line below 
                || (\is_array($propertySchemaType) ? \array_key_exists('string', $propertySchemaType) : 'string' !== $propertySchemaType)
                || ($propertySchema['format'] ?? $propertySchema['enum'] ?? false)
            )
        ) {
            $schema->getDefinitions()[$definitionName]['properties'][$normalizedPropertyName] = new \ArrayObject($propertySchema);

            return;
        }

I'm trying to understand why there's a special case against string? It seems to make the code goes on trying to find out the type by itself and then generate.

[soyuka]

Use schema not openApiContext it'll set https://github.com/api-platform/core/blob/main/src/JsonSchema/SchemaFactory.php#L84 and shouldn't be changed.

[monitaurus]

Wow thanks. I knew that openapiContext was deprecated, but I thought it was only for operation in favor of openapi.
Is there any documentation stating that schema is to use to change the openapi schema?

[soyuka]

openapiContext is deprecated on resources, not on properties if I remember correctly, probably that we should document this indeed!

[monitaurus]

I could give help by editing the "OpenAPI Specification Support (formerly Swagger)" page. But could you give me some insights:

• why editing OpenAPI on operations go through openapi and for properties through schema?
• is schema will edit change openapi and jsonschema?