Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

Problem with schema descriptions

Đang mở
  • Có gì không ổn?
#8,164 0 bình luận 2 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
4/5
Thời gian dự kiến
3-5 ngày
Mức phù hợp với người mới
42/100
Loại issue
Lỗi
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Đình trệ
Công nghệ
openapi, php
Lĩnh vực
api

Hướng nghiên cứu

Bắt đầu bằng cách theo dõi quá trình tạo schema OpenAPI cho các thuộc tính enum tùy chỉnh và so sánh với cách xử lý mô tả PHPDoc hiện có cho các thuộc tính vô hướng. Được xem là hoàn tất khi đặc tả OpenAPI được tạo bao gồm mô tả PHPDoc của thuộc tính mà không yêu cầu mô tả rõ ràng trong schema ApiProperty.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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.
Ngôn ngữ chính
PHP
Star
2.6k
Fork
989
Merge trung bình
1 ngày 22 giờ
Pull request đã merge (30 ngày)
100

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của api-platform/core

Tất cả issue của api-platform/core

Issue tương tự

Thêm issue về PHP

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.