Hacktoberfest 2026：メンテナが10月に向けて印を付けた、オープンで初心者向けの issue。 Hacktoberfest の issue を見る

Problem with schema descriptions

オープン
  • 何か問題がありますか？
#8,164 コメント 0 件 リアクション 2 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

まだ誰も着手していません。

評価

難易度
4/5
見積もり時間
3〜5日
初心者へのやさしさ
42/100
issue の種類
バグ
明瞭さ
おおむね明確
活発さ
停滞
技術スタック
openapi, php
領域
api

調査の方向性

まず、カスタム enum プロパティの OpenAPI スキーマ生成を追跡し、スカラー プロパティに対する既存の PHPDoc 説明の処理と比較します。生成された OpenAPI 仕様に、ApiProperty スキーマで明示的な説明を指定しなくてもプロパティの PHPDoc 説明が含まれていれば完了です。

索引モデルが 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
平均マージ
2日 1時間
マージ済み PR（30日）
104

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

api-platform/core のほかの issue

api-platform/core の issue をすべて見る

似ている issue

PHP の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。