Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

Problem with schema descriptions

Abierto
  • ¿Algo no está bien?
#8,164 0 comentarios 2 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
42/100
Tipo de issue
Error
Claridad
Bastante claro
Estado de actividad
Estancado
Stack tecnológico
openapi, php
Área
api

Línea de trabajo

Comienza rastreando la generación del esquema OpenAPI para propiedades de enum personalizadas y compárala con el manejo existente de las descripciones PHPDoc para propiedades escalares. Se considera terminado cuando la especificación OpenAPI generada incluye la descripción PHPDoc de la propiedad sin requerir una descripción explícita en el esquema ApiProperty.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

OpenAPI

API Platform version(s) affected: 4.1.8

Description
When using a custom enum as a property type, the OpenAPI description must be explicitly defined using the #[ApiProperty(schema: ['description' => '...'])] attribute.
In contrast, for scalar or other non-enum types, the description can be extracted automatically from the PHPDoc comment block.

This inconsistency can lead to confusion and additional boilerplate when using enums.

How to reproduce

class ChecklistQuestionTypeType extends Type implements TypeNameInterface {
    case ACTIVE = 'active';
    case INACTIVE = 'inactive';

    public const array MAPPED_VALUES = [
        1 => self::ACTIVE,
        2 => self::INACTIVE,
    ];

    public const array VALUES = [...self::MAPPED_VALUES];

    public function getValues(): array
    {
        return self::VALUES;
    }

    public function getMappedValues(): array
    {
        return self::MAPPED_VALUES;
    }
}

final class ExampleResource
{
    /**
     * The current status of the resource.
     */
    #[ApiProperty(schema: ['type' => 'string', 'enum' => Status::VALUES])]
    public string $status;
}

Expected: The OpenAPI spec should include the description from the PHPDoc (The current status of the resource.).
Actual: The description is missing unless explicitly added in the ApiProperty attribute like so:

#[ApiProperty(schema: ['description' => 'The current status of the resource.', ...])]

Additional Context

  • The inconsistency suggests that PHPDoc parsing is skipped or not supported for enum types.
  • It would improve DX if enum properties behaved consistently with scalar types regarding description inference.
Lenguaje dominante
PHP
Estrellas
2.6k
Forks
989
Merge medio
1 d 23 h
PR fusionados (30 d)
102

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de api-platform/core

Todos los issues de api-platform/core

Issues similares

Más issues de PHP

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.