Hacktoberfest 2026：维护者为十月标记出来的 issue，仍然开放、适合新手。 浏览 Hacktoberfest issue

Problem with schema descriptions

未关闭
  • 哪里不对？
#8,164 0 条评论 2 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 1 天内回复

还没有人认领这个 Issue。

评估

难度
4/5
预计耗时
3-5 天
新手友好度
42/100
Issue 类型
缺陷
描述清晰度
基本清楚
活跃度
停滞
技术栈
openapi, php
领域
api

调研方向

首先跟踪自定义枚举属性的 OpenAPI schema 生成过程，并将其与现有的标量属性 PHPDoc 描述处理进行比较。完成的标准是：生成的 OpenAPI 规范包含该属性的 PHPDoc 描述，而无需在 ApiProperty schema 中显式提供描述。

由索引模型根据 Issue 内容生成。

描述

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.
主要语言
PHP
星标
2.6k
派生
989
平均合并
1 天 23 小时
30 天内合并 PR
102

环境准备

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

api-platform/core 的其他 Issue

查看 api-platform/core 的全部 Issue

相似的 Issue

更多 PHP Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。